Release notes for Open Source OSS version v4.1test0-070717
=============
What is the open sourced version
--------------------------------
It is an open source version of the Open Sound System (OSS)
sound subsystem software released under the GPL license. The only
difference to the "binary" version of OSS
is that few drivers made by 3rd parties (mostly for professional high end
devices) have been omitted because 4Front Technologies doesn't own the
copyrights to this code. The same is true with few audio enhancement
effects that are not important to the functionality of OSS.
There are two source packages released by 4Front Technologies. The official
package is released under GPLv2 and it contains the OS interfaces for all
supported operating systems. Another version is released under the CDDL license
but it contains only the Solaris and BSD specific parts (the same files may also be
included in the OpenSolaris source distribution). Please use the GPL version if
you are going to make any changes to OSS (even if you are doing development for
Solaris/OpenSolaris or BSD). The CDDL version will be produced from the GPLed source
tree using an automated tool. We cannot accept any contributions based on the
CDDL source tree.
Note that while the GPL package contains sources for all the operating systems
the GPL license is not compatible with any closed source operating systems.
This means that you will need to purchase a commercial license from 4Front
Technologies to use OSS legally with such operating systems.
See www.opensound.com for more information about OSS. Our developer web site
(http://developer.opensound.com) will give additional information for
application developers and OSS contributors.
NOTICE! In general it is not possible to mix binary modules from the retail OSS
package with remainder of the software compiled from open source OSS sources
because certain heased files and core data structures are incompatible. If you
need to use one of the drivers missing from the open source version you will
have to use the retail version of OSS instead.
However there is one special case where you can mix modules from the open source
version with some modules from the retail one. You need to make sure you are
using exactly the source package that matches the retail version (see
www.opensound.com for more info). In (and only in) this case you can check the
right compile time stamp (YYYYMMDDhhmm) from /dev/sndstat and then edit the
timestamp.h files (there may be one or two of them) after running the configure
script. Set the define for osdev_create to have the right time stamp and
build/install the open source version on top of the previously installed retail
version. This method is not officially supported by 4Front technologies because
even minor differences in the key structures may crash the syetem. In
particular do not modify any of the "global" header files if ysing this
approach.
Build system requirements
-------------------------
To be able to extract the source files from the tarball you will
beed the bunzip2 command in the system. It's usually available by default
but otherwise you will need to download the sources from the net and compile it.
OSS is currently compatible with the following
operating systems and processor architectures. Other environments
may be supported later.
Operating system Version Processor architecture
Sun Solaris 10 or later x86, amd64, Sparc (64 bit)
Sun OpenSolaris NV11 or later x86, amd64, Sparc (64 bit)
Linux 2.6.11 or later x86, x86_64
FreeBSD 5.4 or later x86, x86_64
SCO UnixWare 7 or later x86
SCO OpenServer 6 or later x86
The system used to build OSS should have full kernel/driver development
environment installed (C/C++ compiler, linker, make, kernel headers, etc).
Please refer to the documentation of the operating system you are using
Under Linux and FreeBSD the C compiler to use is GCC (_MUST_ be v3.0 or later).
With the other operating systems you need to use the C compiler provided by
the operating system vendor.
In addition GNU awk needs to be available in the system as gwak. Otherwise the
manual pages will not be created correctly (otherwise OSS will compile and
work OK).
Target system requirements
--------------------------
OSS can be installed in a different computer system than where the
software was compiled (OTOH in many cases these systems are the same machine).
Under Linux and FreeBSD some parts of the software need to be compiled in
the target system to handle differences between different kernel versions. For
this reason it's necessary to have a functional kernel development system
installed in the target machine too. In FreeBSD this is the default.
Under Linux systems the target machine should have the following packages
installed (unfortunatgely they are not installed by default.
- Kernel sources and/or headers for the currently active kernel. In most
Linux distributions this package is called kernel-sourcce or kernel-devel.
- C compiler (gcc) version that was used to compile the kernel.
- GNU make.
- GNU binutils.
- GNU awk (gawk)
- Standard C library (libc/glibc) headers.
- GTK+ (version 1.2.x for Solaris and Unixware and version 2.x for others)
Source directory structure
--------------------------
The directory scheme of OSS is different from most other software
packages. Instead of storing source files in the "build" tree we have separated
the build (object) directory from the source directory. In this way the sources
can be located in a common directory on a (NFS) server and shared between
several "build" machines possibly running different operating systems. Any
number of build machines can be used to compile OSS at the same time without
disturbing each other. However nothing prevents having the source directory
located in the local machine or even on CD-ROM or some other read-only media.
There is nothing special in the source directory. It's contents are distributed
in the source tarball (oss-v4.1test0-070717-src-gpl.tar.bz2).
The build directory is a special directory that contains symbolic links to
the corresponding files in the source directory. Files in the build directory
can be edited and the changes will be directed to the original file in the
source directory (provided that it's writeable). However the object files will
only be created in the local build directory only.
Note that there is also some C code (.c and .inc files) that are not built in
the source system but in the target. These files are located in
the setup/`uname`/oss directory. This is necessary because certain kernel data
structures depend on the kernel version being installed in the target system.
The goal of this mechanism is that majority of the code can be compiled in
any system. Only the kernel version dependent parts (wrappers) need to be
compiled in the target system (this mechanism will become unnecessary in the
future when these operating systems (Linux in particular) get a proper
device driver interface.
Installing the sources
----------------------
Save the tarball containing the source files in /tmp (or some other
directory in the development system). In this document we will assume
that you have stored the sources in /tmp/oss-v4.1test0-070717-src-gpl.tar.bz2.
Go to the directory where you would like to create the source directory.
For example:
cd /usr/src
Next restore the files in the tarball by executing the following command:
bunzip2 -c /tmp/oss-v4.1test0-070717-src-gpl.tar.bz2 | tar xvf -
(Or if you have GNU make (Linux, FreeBSD) you simply use
tar xvfj /tmp/oss-v4.1test0-070717-src-gpl.tar.bz2).
After restoring the files they will appear in the oss-v4.1test0-070717-src-gpl
subdirectory under the current directory.
Note! bunzip2 command is part of the bzip2 package.
Creating the build environment
------------------------------
If you have an earlier OSS build directory in the system it's recommended that
you remove it before creating the build directory for v4.1test0-070717
alternatively you may create separate build directories for different
OSS versions.
Before you can build OSS you will need to create an empty "build" directory
and run the configure script. This as well as the actual compile/build step can
be done by any user (ie super user capabilities are not required).
The build directory can be located anywhere (say in your home directory).
However the directory must be completely empty (no files in it). For example
you can create and initialize the build directory in the following way
(assuming that the source directory is /usr/src/$TARGETDIR):
mkdir oss
cd oss
/usr/src/$TARGETDIR/configure
The configure script will perform slightly different steps depending on the
current operating system.
SCO Open Server and SCO UnixWare are regarded as the same plattform and the
same OSS package will work under both of them.
Solaris environment differs from the other operating systems because the
same build will compile both 32 and 64 bit drivers. So there will be two
almost identical subdirectory trees (i386 and amd64) under Solaris.
Some drivers only work under x86 or certain operating systems. For this reason
not all drivers will get compiled in some environments.
Compiling OSS
-------------
You can compile OSS by running make under the build directory. This will
only compile the C source files to binary objects but doesn't actually build
the installable files. There are few make targets that are used to
build the software in different ways:
make build:
This command compiles the binaries and runs the ./build.sh script
(OS dependent) to create the full prototype tree (./prototype). This directory
contains a copy of the files to be installed in the target system (relative
to the / directory).
make install:
This command does "make build" and then copies the files/directories located
in the ./prototype subdirectory to their proper places (under /). After that
the script performs the (OS dependent) steps required to install the drivers
in the local system. It may be necessary to run soundoff and soundon to reload
the drivers in the kernel after running "make install".
This method is a fast way to recompile and install OSS in the system
when hacking with the drivers. However it's necessary to create the proper
installation package and install it when installing a new OSS version
for the first time.
make package:
This command will compile the OSS software and buil a proper installation
package (.rpm, .pkg or something else depending on the operating system).
This package (from the local directory) can then be installed in the target
system (local computer or somewhere else) using the usual software installation
and management tools (pkgadd/pkgrm, rpm) provided by the operating system.
Notice that this command may not work properly in all Linux systems because
most Linux distributions are incompatible with each other. So the
files/scripts used to create the RPM package may need to be edited if you are
using any other distribution than SuSE or Redhat/Fedora. In particular Debian
style package management is not supported. If you are installing OSS in a
noncompatible system you will have to use "make install" (or to move the
files using a tar package and then run the install script
(cd /usr/lib/oss/build;sh install.sh).
Summary: (This is how we build OSS at 4front)
---------------------------------------------
1) cd /usr/src; tar -jxvf oss-v4.1test0-070717-src-gpl.tar.bz2
2) mkdir /usr/src/oss; cd /usr/src/oss
3) /usr/src/$TARGETDIR/configure
4) make install
This step compiles the software and copies the files to their right
places. Finally it starts the drivers using the soundon script.
Installing the compiled (binary) package in the target system
-------------------------------------------------------------
After running make package the install package (.pkg/.rpm) will be created in
the build directory. This package can be moved to the target system and
installed using the pkgadd or rpm commands.
Managing OSS installation
-------------------------
OSS can be started and stopped by using the soundon and soundoff commands
(respectively). Soundon will create a log file (/usr/lib/oss/logs/soundon.log)
that contains debugging information that helps in solving problems with OSS.
Installing the OSS package will also install a startup script (usually
/etc/rc3.d/S89oss) that will start OSS automatically when the system gets
rebooted. So running soundoff or soundon is manually is rarely necessary.
Information about the devices in the system can be printed using
the ossinfo command (ossinfo -v3 for most detailed output).
When new hardware is installed in ths system it is usually necessary to
run the ossdetect utility (ossdetect -v for verbose output) to find the new
devices in the system. After running ossdetect you will need to run soundoff
and soundon to reload the drivers (not necessary under Solaris).
Configuration options
---------------------
The /usr/lib/oss/conf directory will contain various configuration
files (or actually symbolic links to the actual files in system dependent
directories). These files can be edited using any text editor to change the
settings. However there is rarely need to change these settings.
You need to run soundoff and soundon to make the config option changes
to take effect. Under SCO OpenServer and UnixWare you will also need to run
the following commands _before_ doing soundoff;soundon:
cd /usr/lib/oss/build
sh install.sh
Developing OSS compatible applications
--------------------------------------
The OSS API is documented in the OSS Programmer's Guide
(http://manuals.opensound.com/developer).
Making modifications to Open Sound System
-----------------------------------------
If you plan to make modifications to Open Sound System, please check
our developer web site (http://developer.opensound.com) before doing anything.
Also it's recommended that you join the oss-devel mailing list and describe
the changes you are planning to do. We will accept contributions to the code.
However there are certain rules the contributions must follow before they can
be accepted. First of all the contributions must not cause any compatibility
problems between different OSS versions. Also changes that may increase
complexity of the OSS API or could cause incompatibilities between devices will
probably not be accepted.