Show install.texi syntax highlighted
@node Source installation
@chapter Source installation
This chapter shows the steps to get a working version of Marsyas.
Complete each section fully before attempting the next section.
@menu
* System preparation::
* Download::
* Configuring::
* Compiling::
* Installing::
* Post-install optional configuration::
* Platform-specific notes while running Marsyas::
* Structure of distribution::
@end menu
@node System preparation
@section System preparation
@menu
* Requirements on *nix (including MacOS X)::
* Requirements on Windows::
* Optional programs and datasets::
@end menu
@node Requirements on *nix (including MacOS X)
@subsection Requirements on *nix (including MacOS X)
@unnumberedsubsubsec Linux
Required:
@itemize
@item Standard development environment (gcc, g++, etc): probably already
installed.
@item @uref{http://www.alsa-project.org/,ALSA} headers. On most
distributions, this is a package called @code{alsa-devel} or
@code{libalsa-devel}.
@end itemize
Strongly recommended:
@itemize
@item @uref{http://www.trolltech.com/products/qt,Qt/Trolltech}
development platform, version 4.2.3 or above.
@end itemize
@unnumberedsubsubsec MacOS X
Required:
@itemize
@item @uref{http://developer.apple.com/tools/xcode/, Xcode}: standard
development platform on OSX. Please install from your OSX installation
CD/DVD, or download.
@end itemize
Strongly recommended:
@itemize
@item X11: unix windowing system, included as an extra on your OSX
installation CD/DVD.
@item @uref{http://www.trolltech.com/products/qt,Qt/Trolltech}
development platform, version 4.2.3 or above.
@end itemize
@node Requirements on Windows
@subsection Requirements on Windows
On Windows, you may use either MinGW, Microsoft Visual Studio, or
Cygwin.
@unnumberedsubsubsec MinGW
MinGW is a collection of compilers, compiler tools, libraries, and
header files, which can compile code on Windows. This is the main
supported compiler for Qt/OpenSource; it is installed by default as part
of the normal Qt installation on Windows.
Required:
@itemize
@item @uref{http://www.mingw.org/, MinGW} (installed by default by
Qt/OpenSource)
@item @uref{http://www.trolltech.com/products/qt,Qt/Trolltech}
development platform, version 4.2.3 or above.
@item Microsoft DirectX SDK and Platform SDK
@end itemize
@unnumberedsubsubsec Cygwin
Cygwin is a unix environment for Windows.
Required:
@itemize
@item @uref{http://www.cygwin.com/,Cygwin}, with gcc and autotools
installed (these should be installed by default)
@item Microsoft DirectX SDK and Platform SDK
@end itemize
Strongly recommended:
@itemize
@item @uref{http://www.trolltech.com/products/qt,Qt/Trolltech}
development platform, version 4.2.3 or above.
@end itemize
@unnumberedsubsubsec Microsoft Visual Studio
Windows XP SP2 has been tested; in theory other versions of Windows
should work, but they have not been tested.
Required:
@itemize
@item Latest version of
@uref{http://www.microsoft.com/downloads/details.aspx?FamilyId=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en,
Microsoft Platform SDK}
@item @uref{http://msdn2.microsoft.com/en-us/xna/aa937781.aspx,
Microsoft DirectX SDK}
@item @uref{http://msdn.microsoft.com/vstudio/express/, Microsoft Visual
Studio 2005 Express} (similar instructions will work for MSVC 2005
Professional) (previous versions of MSVC will probably work, but have
not been tested)
Only Visual C++ and .Net 2.0 libraries included with MSVS install
packages are needed for Marsyas building.
@item @uref{http://www.trolltech.com/products/qt,Qt/Trolltech}
development platform, version 4.2.3 or above. For use with MSVS2005,
download the qt-win-opensource-src-4.3.0.zip file (i.e. without the
MinGW compiler) from Trolltech's website.
@item (OPTIONAL) WEVE (Windows Environement Variable Editor -
@uref{http://www.silvermace.com/weve/}): allows easy editing of Windows
environment variables. Highly recommended.
@end itemize
@subsubheading Installation
@example
a) Install Microsoft Platform SDK into your system
b) Install Microsoft DirectX SDK into your system
c) Install MSVS2005 into your system (you can get a free version of
MSVS2005, known as MSVS2005 Express). Only Visual C++ and .Net 2.0
libraries included with MSVS install packages are needed for Marsyas
building.
d) After installing the SDKs and MSVS2005 as instructed, make sure that
your following Windows User and System Variables at least include
similar entries as presented bellow (paths may be slightly different
depending on where you installed your applications and SDKs as well as
depending on the versions of the SDKs installed - see WEVE for a nice
tool to easily set and verify Windows env. Vars):
@end example
@subsubheading System Environment Variables
@example
Path
C:\Program Files\Microsoft DirectX SDK (June 2007)\Utilities\Bin\x86
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin\.
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Bin\WinNT\.
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\bin
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
C:\Program Files\Microsoft Visual Studio 8\VC\VCPackages
C:\Program Files\Microsoft Visual Studio 8\Common7\IDE
C:\Program Files\Microsoft Visual Studio 8\VC\BIN
VS80COMNTOOLS
C:\Program Files\Microsoft Visual Studio 8\Common7\Tools\
Basemake
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Include\BKOffice.Mak
Bkoffice
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
INCLUDE
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Include\.
C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE
INETSDK
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
LIB
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib\.
C:\Program Files\Microsoft Visual Studio 8\VC\LIB
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib
MSSdk
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
Mstools
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
LIBPATH
C:\WINDOWS\Microsoft.NET\Framework\v2.0.50727
VSINSTALLDIR
C:\Program Files\Microsoft Visual Studio 8
VCINSTALLDIR
C:\Program Files\Microsoft Visual Studio 8\VC
FrameworkDir
C:\WINDOWS\Microsoft.NET\Framework
FrameworkVersion=v2.0.50727
FrameworkSDKDir
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0
DXSDK_DIR
C:\Program Files\Microsoft DirectX SDK (June 2007)\
@end example
@subsubheading System Environment Variables
@example
Basemake
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Include\BKOffice.Mak
Bkoffice
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
INCLUDE
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Include\.
C:\Program Files\Microsoft Visual Studio 8\VC\INCLUDE
INETSDK
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
LIB
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib\.
C:\Program Files\Microsoft Visual Studio 8\VC\LIB;
C:\Program Files\Microsoft Visual Studio 8\SDK\v2.0\lib
%DXSDK_DIR%\Lib\x86
MSSdk
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
Mstools
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\.
PATH
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Bin\.
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Bin\WinNT\.
@end example
@subsubheading More installation instructions
@example
e) Download Trolltech's Qt4 opensource library and uncompress the
downloaded .zip file (e.g. qt-win-opensource-src-4.3.0.zip) into the
folder in your disk where you want Qt to be installed (a good suggestion
is to use a path containing no spaces, such as c:\Qt\4.3.0-msvc2005 or
something similar).
f) For using the Qt4 opensource with MSVS2005, Qt4 source code must be
patched (Trolltech only provides official support for the MinGW compiler
on Qt4 opensource - see corresponding section on this documentation on
how to build Marsyas with Qt4 using the MinGW compiler). If you are
using a commercial license of Qt4 for Windows, MSVS2005 support is
already included and you should skip this step! Point your web browser
to http://qtnode.net/wiki?title=Qt4_with_Visual_Studio and carefully
follow the instructions presented there (some of them include some of
the steps already presented above). After succesfully patching and
building Qt4 (this step will take quite some time to complete - go grab
a coffee and/or keep reading this documentation ;-)), be sure that your
user env. vars in Windows include the following info:
-----------------
USER ENV. VARS:
-----------------
QTDIR
C:\Qt\4.3.0-msvc2005
Path
%QTDIR%\bin;
INCLUDE
%QTDIR%\include
QMAKESPEC
win32-msvc2005
g) In order to be able to build Marsyas Projects in MSVS2005, go to the
MSVS2005 menu Tools->Options...->Projects and Solutions->VC++
Directories and make sure that the following lines are listed in the
"include files" and "library files" directories path lists (yes, this
should be taken care by the SDKs installs, but strangely it some times
doesn't happen):
INCLUDE FILES DIRECTORIES:
--------------------------
C:\Program Files\Microsoft Platform SDK for Windows Server 2003
R2\Include\.
LIB FILES DIRECTORIES:
-----------------------
C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Lib\.
h) If you followed these instructions carefully, you should now be ready
to get Marsyas (from a tar ball in sourceforge or from sourceforge SVN -
see http://marsyas.sf.net) and build it using Trolltech's qmake utility
to build Marsyas (installed during steps 2.e and 2.f above) . Go to the
directory where you extracted the Marsyas tarball (or where you checked
out Marsyas from the sourceforge SVN server to - btw, have a look at
this very nice SVN client utility for windows:
http://tortoisesvn.tigris.org/) and open a cmd window there and type the
following cmd lines for building Marsyas and some of the included apps
and examples in release:
C:\MyMarsyasDir > qmake
C:\MyMarsyasDir > nmake release
This should build the Marsyas library (i.e. marsyas.lib, which you can
find in c:\MyMarsyasDir\lib\release) and some of the applications and
examples (that you can find and execute in c:\MyMarsyasDir\bin\release).
i) You can generate MSVS2005 project files (.vcproj) for both the
Marsyas lib and all the apps and examples using qmake and the .pro
project files included in Marsyas (both release and debug solution
configurations will be created in MSVS2005). This will allow you to open
Marsyas projects in MSVS2005 and use its nice IDE for code
writing/editing, building and most importantly debugging. For creating a
MSVS2005 project for the Marsyas (static) library, open a cmd window on
the marsyas directory in your Marsyas folder and run the following qmake
command:
C:\MyMarsyasDir\marsyas > qmake -t vclib
This will generate a marsyas.vcproj file that you can open in MSVS2005
to edit and build.
For creating a MSVS2005 project for a Marsyas application (e.g. sfplay),
go to its folder and execute:
C:\MyMarsyasDir\apps\sfplay > qmake -t vcapp
You will get a sfplay.vcproj that you can once again open in MSVS2005.
If you need to debug your application using MSVS2005, it's a nice idea
to create a MSVS2005 Solution that includes the marsyas.vcproj and your
application .vcproj. If you then define a dependency of your application
to the marsyas.vcproj (check MSVS2005 documentation), MSVS2005 will then
always check if it needs to also build the Marsyas lib before linking it
to your application. Furthermore, having set up this Solution allows you
to debug into Marsyas library code (e.g. put breakpoints in your
application code as well as in Marsyas lib code, watches, memory views,
call stacks, etc). Check qmake and MSVS2005 documentation for more
details.
j) Read carefully the remaining of this fine documentation (RTFM ;-))
and in case of questions, problems or suggestions, do not hesitate to
post an email to Marsyas User and Developers Mailing lists:
marsyas-users@@lists.sourceforge.net
marsyas-developers@@lists.sourceforge.net
@end example
@node Optional programs and datasets
@subsection Optional programs and datasets
Useful libraries:
@itemize
@item
@uref{http://sourceforge.net/projects/mad/, LibMAD}: mp3 support
@end itemize
Useful programs:
@itemize
@item
@uref{http://python.org, Python}: Installed by default on Linux and MacOS X
machines; Windows users may install it from this site. Marsyas contains
some very useful scripts which are written in Python.
@item
@uref{http://www.mathworks.com/products/matlab/, Matlab}: information
may be easily passed to and from Matlab and Marsyas; this allows easy
prototyping.
@end itemize
Useful datasets:
@itemize
@item
@uref{http://marsyas.sness.net/marsyas-coffee/marsyas-coffee-latest.tar.bz2,
marsyas-coffee}:
data set used for large regression tests in Marsyas.
@end itemize
@node Download
@section Download
@subsection Stable(-ish) Version
(@i{Important Note: Marsyas does not use CVS any more; any links to
"marsyas CVS" are hopelessly out of date})
Marsyas is hosted at SourceForge:
@example
@uref{http://marsyas.sourceforge.net/}
@uref{http://www.sourceforge.net/projects/marsyas}
@end example
Marsyas is open source software and is distributed
as a tarball (something like @file{marsyas-0.2.8.tar.gz}). Uncompress
this file using whatever uncompression program you prefer (@code{tar -xf},
winzip, etc).
@subsection Development Version
The latest version can be obtained from the subversion repository
stored at the sourceforge website. Although constantly in flux the
latest version is typically relatively stable and usable and if it is not
we are quick in fixing it. In contrast releases happen infrequently.
If you are planning on working extensively with Marsyas and writing
your own source code it is highly recommend that you download a
subversion working copy. If you only require one of the tools provided
in Marsyas and don't plan to explore the framework then the regular
releases should suffice. To check out a working copy do:
@example
svn co https://marsyas.svn.sourceforge.net/svnroot/marsyas/trunk my-marsyas-dir
@end example
You can replace @file{my-marsyas-dir} with any directory you want. The
version/release (version 0.2 release 10) is independently assigned
from subversion revisions and the latest can be found by checking
the sourceforge website.
@node Configuring
@section Configuring
@subsection ...with autotools
Marsyas may be compiled using the standard GNU configure script:
@example
./configure
@end example
Marsyas can be customized using various configuration options. The
current list of available options can be viewed by typing:
@example
./configure --help
@end example
For example, to compile Marsyas and MarsyasQt with mp3 support through
libmad and writing warnings to a file, one would do:
@example
./configure --enable-marsyasqt --with-mad --enable-log2file
@end example
@warning{If you want to write Marsyas/Qt programs, you must configure
with @code{--enable-marsyasqt}}
A frequent variation (if you don't have root priviledges)
is to install Marsyas in your home directory:
@example
./configure --enable-marsyasqt --prefix=$HOME
@end example
@unnumberedsubsubsec Debugging options
@example
./configure --enable-marsyasqt --enable-debug \
--enable-assert --enable-warnings --enable-diagnostics \
--enable-log2file
make clean
make
@end example
The resulting program can be run under @code{gdb} to track down problems.
@subsection ...with qmake
Marsyas can be built with qmake, which is the Makefile generator in
Qt. To build Marsyas, go to the base of the source tree and edit
@file{marsyasConfig.pri}. You will probably want to change the settings
for @emph{release/debug mode}, @emph{WARNINGS/LOGS}, and @emph{MATLAB
engine classes}, and @emph{MP3 MAD}.
Once you have selected the options you want, simply type
@example
qmake
@end example
@c the @warning{} needs everything on one line. :(
@warning{on MacOS X and when using Qt-4.3.0 or higher, you must add
@w{@code{export QMAKESPEC=/usr/local/Qt4.3/mkspecs/macx-g++/}} to your
@file{~/.profile} and then close (and re-open) your terminal window}
@node Compiling
@section Compiling
@subsection ...on *nix (including MacOS X)
After @ref{Configuring}, simply type
@example
make
@end example
@subsection ...on Windows (MinGW or Visual Studio)
After @ref{Configuring}, simply type
@example
nmake (nmake debug or nmake all for debug or debug and release builds)
@end example
This builds marsyas.lib, all (at least most of them) command line apps
(sfplay, bextract, etc) and MarPlayer and MarPhasevocoder.
To generate a MSVC .vcproj for a project just cd into the app dir (e.g.
apps/Qt4Apps/Meaws) and do:
@example
qmake -t vcapp
@end example
In case you also want to create a .vcproj for the marsyas lib, cd into
marsyas dir and do:
@example
qmake -t vclib
@end example
@subsection Testing the build
After you have compiled Marsyas, it is highly recommended to perform our
automatic tests. For more information, see @ref{Regression tests}.
@node Installing
@section Installing
@subsection ...with autotools
To install, type
@example
make install
@end example
If you are trying to write to a system-wide location (such as the
default value of @file{/usr/local} ), you must be be root. To change
the installation directory, configure with @code{--prefix=DIR}.
@subsection ...with qmake
Marsyas built with qmake cannot be installed; you must link to the
library directly in the source tree.
@node Post-install optional configuration
@section Post-install optional configuration
@menu
* Vim editor support::
* MATLAB setup::
@end menu
@node Vim editor support
@subsection Vim editor support
A syntax file for vim color highlighting is in @file{misc/marsyas.vim}.
To use this file, copy it to @file{$HOME/.vim/syntax} add the following
lines to @file{$HOME/.vim/filetype.vim}:
@example
if exists("did_load_filetypes")
finish
endif
augroup filetypedetect
au! BufNewFile,BufRead *.cpp setf marsyas
au! BufNewFile,BufRead *.h setf marsyas
augroup END
@end example
@node MATLAB setup
@subsection MATLAB setup
MATLAB is a blah blah blah.
@WANTED{blurb about matlab}
@WANTED{docs for matlab on other OS}
@unnumberedsubsubsec ... on OSX (Intel)
(the powerPC version is slightly different)
@enumerate
@item
MATLAB and X11 for OS X must be installed
@item
The configure script assumes it is installed in
/Applications/MATLAB74
(this should be an environment variable; this might be fixed soon ).
@item
The marsaysMATLABrelease configuration must be enabled
(uncommented in marsyasConfig.pri, or do something for autotools)
@item
Compile Marsyas using qmake, make
@item
try out marsyasTests -t MATLABengine. MATLAB
should open and various benchmarks and communication
between Marsyas and MATLAB should happen. If not
email the mailing lists for some help.
@item
There must be a symbolic link to the matlab executable
from /usr/bin/matlab:
ln -s /Applications/MATLAB74/bin/matlab /usr/bin/matlab
@item
You must start X11 windows manually. "open -a X11", or click on the X11
icon in your /Applications/util/ folder.
@end enumerate
@node Platform-specific notes while running Marsyas
@section Platform-specific notes while running Marsyas
@subsection Linux
@cindex Linux notes
No specific notes.
@subsection Mac OSX
@cindex Mac OSX notes
When trying to record audio, the sample rate must be specified
explicitly:
@example
pnet->addMarSystem(mng.create("AudioSource", "srcRec"));
pnet->updctrl("mrs_real/israte", 44100.0);
pnet->updctrl("AudioSource/srcRec/mrs_bool/initAudio", true);
@end example
@subsection Windows
@cindex Window notes
No specific notes.
@node Structure of distribution
@section Structure of distribution
@c file structure
Marsyas is primarily targeted to researchers and software developers who
want to build new systems and applications using existing building
blocks. Therefore familiarity with the directory structure of the
Marsyas distribution is important for any serious work with the
framework.
The main marsyas directory consists of the following important files:
@itemize
@item @b{NEWS:} important changes in each release.
@item @b{AUTHORS:} who we are, what we do.
@item @b{marsyasConfig.pri:} edit this file to select your configure
options when using qmake.
@item @b{INSTALL, COPYING, README, Changelog:} standard text files for
GNU projects, but not relevant to ours. We use @code{svn log} messages
instead of the Changelog, and the documentation is covered in this
manual.
@end itemize
@noindent
In addition there are the following subdirectories:
@itemize
@item @b{src:} all the C++ source files.
@item @b{src/marsyas:} the main directory containing all the important
source code of Marsyas. The source files in this subdirectory are
compiled into a static library that other programs can use to access
Marsyas functionality.
@item @b{src/apps:} the source code for executables.
@item @b{src/examples:} easy-to-read source code for simple executables.
@item @b{src/marsyasqt_wrapper:} source for the static library
MarsyasQt, which allows the use of Marsyas in Qt applications.
@item @b{src/Qt4Apps:} provides GUI interfaces using Qt4. These will not
work with earlier versions of Qt. You must have Qt4 installed in order
to use or compile these applications. A README file is supplied with
each one that has instructions on how to compile and run it.
@item @b{bin:} executable files are compiled in @file{bin/release} or
@file{bin/debug}.
@item @b{doc:} contains the user manual (which you are currently
reading).
@item @b{config:} configuration files used by autotools.
@item @b{scripts:} useful scripts to help programming with Marsyas.
@item @b{scripts/MATLAB:} MATLAB scripts.
@item @b{regressionTests:} data files for our automatic tests.
@end itemize
See more files for this project here