Sfront Reference Manual: Part I/1: Installing Sfront
Description: A part of the Sfront reference manual, that describes how to install the program. Sfront is a program that translates MP4-SA files into C programs.
Keywords: MP4-SA, SASL, SAOL, MP4, sfront, install, platforms, supported platforms, download, downloading, compile compiling, test, testing, bug, bugs, bug report, submit bug report

### From The `sfront` Reference Manual by John Lazzaro and John Wawrzynek.

# Part II/1: Installing Sfront

## Sections Introduction. Supported platforms. Where sfront runs. Downloading sfront. How to pick up sfront. Compiling sfront. Creating a binary. Testing sfront. Making music with sfront. Bugs. Let us know if things don't work.

## Introduction In this chapter, we describe how set up sfront to work on your machine, and how to test sfront to make sure it works properly. | ##

## Supported Platforms Sfront is written in ANSI C and uses only ANSI C libraries. When executed, sfront creates ANSI C files that only use ANSI C libraries. These attributes make sfront portable over a wide number of platforms, with ancillary files (makefiles, project files, etc.) and real-time support being the primary portability issues. The right panel shows the platforms sfront is currently known to work. A checkbox in the R column indicates basic file rendering functionality. The S, M and N columns indicate support for audio output and input to soundcards, MIDI control input from an external controller, and sfront networking support. We currently provide a generic source distribution, suitable for use on most UNIX variants (including Linux and Mac OS X) as well as Microsoft Windows. The Debian project offers a binary distribution of sfront, which is maintained by Enrique Robledo Arnuncio. We develop sfront under Mac OS X and Linux; the sfront user community is instrumental in porting and testing to other platforms. Thanks to Ross Bencina, Richard Dobson, Michael Gogins, Peter Maas, Kees van Prooijen, and Tim Thompson for Microsoft support. Thanks to Bertrand Petit for FreeBSD support. Thanks to the coreaudio-api and darwin list members, and Manfred Brockhaus, BUYO-BUYO-IGOR, Phil Burk, Richard Dobson, Dominic Mazzoni, and Juno for Mac OS support. Thanks to Michael Pruett for IRIX support. | ## Platform Status `
    OS Type          | R | S | M | N |
    ----------------------------------
    Linux 2.4        | x | x | x | x |
    Mac OS X 10.3    | x | x | x | x |
    MS Windows       | x | x | ? |   |
    IRIX 6.5         | x | x |   | ? |
    Solaris 2.6      | x |   |   | x |
    FreeBSD 3.4      | x | x | ? | ? |
    BeOS 4.5         | x |   |   |   |
    HPUX 9.x         | x | x |   | x |
    ----------------------------------

    Key:

      R: sfront can create a C file,
    that when compiled and executed,
    generates a WAV file containing
    the performance.

      S: C files that can handle
    real-time audio output and input
    from attached soundcards.

      M: Real-time MIDI control input
    from an attached MIDI controller.

      N: Sfront networking support.

    x --> known to work
    ? --> untested drivers, please
          report test results.
` ## Compiler Support `
    Sfront, and the C code sfront
    generates, compiles under gcc
    on all platforms.

    Under Windows, compiles using
    Microsoft Visual C++ compiler
    and Borland C++.

    Under Mac OS X 10.3, compiles
    (slowly!) with cc/gcc.

    Under Mac OS 9, sfront compiles,
    but the C code sfront creates is
    not completely stable (the sample
    wavetable generator and MIDI
    file input are the major issues).
`

## Downloading Sfront Sfront is free software, distributed under the terms of the GNU Public License. See the right panel to learn how to download the source distribution. An official Debian package for sfront also exists. #### Unpacking `wxyz.tar.gz` files The source distributions intended for Mac OS X, Linux, and generic UNIX systems are in the form of a UNIX tar file, compressed with the gzip utility (i.e. `wxyz.tar.gz`, or perhaps `wxyz.tar` if your browser automatically uncompresses files). The commands: ``
    gunzip sfront.tar.gz
    tar -xf sfront.tar
should unpack this file and create the directory sfront. If the download generates the file sfront.tar, only execute the second command. #### Unpacking `wxyz.zip` files The distributions intended for Windows systems are in the form of a ZIP archive. Use a tool such as Pkunzip or WINzip to unpack this file and create the directory sfront. #### The `sfront` directory tree If you downloaded a `tar.gz` or `zip` file, unpacking the file will create a set of subdirectories under the `sfront` directory: ``
    % cd sfront
    % ls
    examples/  sfman/   src/   bin/   lib/
The `examples` directories holds set of MP4-SA files to test sfront. The `src` directory holds the source code to sfront. After compilation, the `bin` directory holds sfront binaries. The `lib` directory holds SAOL programming libraries, including the Slib library of low-level utilities. The `sfman` directory holds a copy of the HTML manual you're reading right now, which starts at ``
    sfman/index.html
Other files and directories may also be present. | ## Download `sfront 0.87, 10/15/04` `
    A source distribution is
    available, which works well
    on Mac OS X, Linux, MS Windows,
    and generic UNIX platforms.

    To read about changes since the
    last distribution, read this
    change log.

    Click on

    [sfront.tar.gz : 4.73 MB]

    or

    [sfront.zip : 4.92 MB]

    to download the full source
    distribution for sfront, which
    includes a large set of examples.

    Click on

    [sfrontlite.tar.gz : 1.03 MB]

    or

    [sfrontlite.zip : 1.23 MB]

    to download a minimal source
    distribution for sfront, which
    includes a smaller set of examples.

    Sfront also has an official
    Debian package maintained
    by Enrique Robledo Arnuncio.
    Enrique's package may contain
    a slightly older sfront version
    than the source distribution above.
` `
    An ANSI C compiler is needed to
    create the sfront binary and to
    compile sfront's output, and a
    version of make is needed to
    try the examples. If you are a
    DOS/Windows user and don't
    have these tools, click on

    [win_gnu.zip : 1.8 MB]

    to download a Windows port of
    the GNU gcc and make. Thanks to
    Ross Bencina for this package.
`

## Compiling sfront To compile sfront under UNIX, begin by `cd`'ing to the `sfront/src` directory. Edit the `Makefile` in this directory, making the changes suggested on the right panel. Once these changes are made, simply type ``
    make install
If all goes well, this command will trigger the compilation of all the C source files that make up `sfront`, then link the object files to create the `sfront` binary, and finally copy the binary to the bin directory specified by the `Makefile`. If all doesn't go well, please let us know so we can do our best to fix the problem. See these instructions for sending a bug report. | ## Makefile options `
    Before starting compilation,
    edit the Makefile and read
    the comments for suggestions
    on how to customize sfront for
    your environment. In particular:

    BINDIR = ../bin/

    BINDIR is where the binary of
    sfront is copied. BINDIR defaults
    to the sfront/bin directory, but
    you may wish to put the binary
    somewhere else. The complete path
    for BINDIR must be in your shell
    path in order to use sfront on
    the command line.

    CC = gcc

    CC specifies the the C compiler.
    On Mac OS X pre-10.2, the Developer
    Tools installs gcc as cc, and so
    "gcc" above must be changed to "cc".

    LINKLIB = -lm

    In some systems, LINKLIB will need
    extra options -- if you find that
    compilation works but linking fails,
    change this line.
`

#### If you use Windows ... If you own the Microsoft Visual C++ or Borland C++ compiler, you can use it to compile `sfront` and the C files it creates, by following the directions above. Microsoft users will need to use the project files locating in the `win/` directory to make sfront. These files were supplied by Richard Dobson. If you don't own a C compiler, you can download the Windows port of the GNU development tools, using the link on the right panel. Thanks to Ross Bencina for putting this download together. To fully use real-time audio support under Windows, you should download and install the latest version of Developer Microsoft DirectSound. | #### GNU Tools for Windows `
    Click here to download a
    ZIP file (1.8 MB) that contains
    the Windows version of the GNU
    C compiler and GNU make.
```

#### If you own a Mac ... We recommend Mac OS X for Macintosh users; sfront compiles and runs well on 10.3, using the gcc compiler that ships with OS X Developer Tools (see right panel). Sfront supports the low-latency audio I/O under OS X using the CoreAudio framework. Sfront also compiles on Mac OS 9, using the the free MPW system to compile sfront and the C files it creates. Build sfront as an MPW tool and add it to your path, so that it can be used as a command-line tool in the MPW shell. Also build sa.c files as MPW-tools. MIDI file and sample file reading is unstable under MPW, and so several of the examples shipped with sfront will not work under OS 9. | #### Developer Tools for Mac OS X `
    The boxed Mac OS X set includes
    a developer CD, that contains
    the Apple cc compiler and many
    other development tools. Some
    new Macs have these developer
    tools installed at the factory.

    You can also obtain these tools
    for free, by becoming an ADC Online
    member, and downloading the tools
    from the ADC website.
`#### MPW for the Mac (Mac OS 9 only) `
    Click here to download a
    free compiler and development
    environment for the Macintosh.
`````

## Testing sfront The sfront distribution includes a set of example files, to test different aspects of the program. The example files are located in subdirectories that are in `sfront/examples`. If you installed a packaged version of sfront, copy `/usr/doc/sfront/examples` to your home directory). Not all sfront distributions contain the same examples, due to file size and legal issues. Each of the example directories share a common structure. The directories include a `Makefile`, a SAOL file, and any other files needed in the example. See the right panel for a description of the examples. Entering any of these directories and typing `make` results in the generation of an `output.wav` audio performance (an exception is the example `in`, which cannot be made until example `beat` is made). Mac OS X users may need to change the CC in each Makefile, from "gcc" to "cc". The simplest example is `examples/min`, which should exist in all sfront distributions. Enter this directory, type `make`, and the command should finish a few seconds later, after running `sfront`, which produces the file `sa.c`. The C compiler, which compiles `sa.c` to produce `sa`. The object file `sa`, which creates the file `output.wav`. If these commands execute, and if the `output.wav` file sounds like a short synthetic melody, then `sfront` works on your system. | ## Sfront Examples `
    The number of examples in
    your sfront distribution
    depends on the type of
    distribution you have.

    Listed below are examples
    which may included in your
    version of sfront. ES
    indicates the example was
    written by Eric Scheirer.

    name       test coverage
    ------------------------
    bach       MIDI files
    beat       SASL table lines (ES).
    claps      AIF soundfile (ES).
    elpelele   MIDI files (ES)
    gliss      sfront control port.
    in         input_bus
    min        general-purpose
    pc         general-purpose (ES)
    perc       spatialize, reverb.
    scr1       MIDI files (ES)
    speedt     WAV soundfile,
               speedt core opcodes.
    torvalds   input_bus, soundfiles
    vowels     parametric filters (ES)
`

For your convenience, the top-level `examples` directory contains a Makefile that generates the `output.wav` file for all of the examples at once. Typing `make` at this level runs all of the examples in order. Depending on your machine, this may take a good fraction of an hour to run. SAOL development using `sfront` is easiest to do using `make`. You may wish to copy the Makefile from one of the examples for your own development work. The right panel shows the list of commands that the `Makefile`s recognize. | ## Makefile Usage `
    invocation      function
    ------------------------
    make          create output.wav
    make clean    delete all created
                  files, including ~'s.
    make mp4test  tests binary encoding
    make safe     cp output.wav safe
    make compare  cmp safe and output.wav
    make timing   times ./sa execution
`

The `rtime` directory contains several examples of audio playback, real-time interactive, and networking uses of sfront. These examples generate real-time low-latency audio output, in response to MIDI and audio input; several examples use the Internet to connect several sfront clients interactively. The right panel describes these examples. All of the examples run under Linux and Max OS X, and some of the examples should run in other environments with real-time sfront support, including SGI Irix and Microsoft Windows. We have tested these examples on an x86 Linux machine using the standard Linux OSS drivers and a PCI 128 soundcard, and on an Apple Powerbook G4 550 Mhz with an Edirol UM-1S USB MIDI interface. To run an example under Linux, `cd` into its directory and type `make`. To run an example under Mac OS X, copy `Makefile.osx` to `Makefile` and type `make`. Examine the README file in each directory to learn how to modify the example for other environments. | ## Interactivity and Networking `
    Examples in the examples/rtime/
    directory are real-time applications,
    that generate audio output in response
    to audio and MIDI input signals.

    name       test coverage
    ------------------------
    aatest     the simplest audio
               test -- streams a
               MIDI file to audio out.
    ascii      monophonic sine-wave
               instrument, played via
               the ASCII keyboard.
    linain     simple reverb unit, that
               processes audio input
               and generates audio out.
    linmidi    polyphonic sine-wave
               instrument, triggered by
               signals on the MIDI In
               port on the soundcard.
    linbuzz    a real-time instrument
               like linmidi, that uses
               Slib to add pitch wheel,
               mod wheel, and channel
               volume controls.
    linvoc     envelope follower patch,
               that uses MIDI In and
               audio in signals together
               and generates audio out.
    mirror     tests sfront networking,
               using a Berkeley-based
               testing service.
    nmp_audio  a client for network
               musical performance.
    nmp_null   a network testing utility
               for use with nmp_audio
    nmp_stream a client for streaming
               MIDI files with low
               latency over a network.
`

## Bugs If you use `sfront` extensively, or if you try to use `sfront` on a new platform, you will probably uncover bugs in the program. By sending a bug report along to us, you can help make `sfront` a better program. The right panel explains what makes a good bug report, and where to send the bug report. Next section: Part I/2: File Rendering | ## Bug Reports `
    Send bug reports to:

    lazzaro@cs.berkeley.edu

    Ideally, include:

    -- ASCII versions of the SAOL
       and SASL files.

    -- The C file sfront produced,
       or the error message sfront
       produced.

    -- If the C file sfront produced
       didn't compile, the compiler
       error messages.

    -- If the file produced by sfront
       crashed while running, any ASCII
       messages printed by sfront or the
       OS.

    -- Information on the platform
       you're running on, including
       type of OS (including version
       number) and type of compiler
       (including version number).

    -- The version number of sfront.

    -- A short note explaining the problem,
       including what you heard.

    -- DON'T send any binary files (.mp4,
       output.wav, ect) at first -- I'll
       let you know if I need them later.
`

Copyright 1999 John Lazzaro and John Wawrzynek.