Release notes for Open Source OSS version v4.2-build2004 ================================================== What is the open sourced version -------------------------------- It is an open source version of the Open Sound System (OSS) sound subsystem software released under the BSD license. The only difference between the "commercial" version and the open source version of OSS is the commercial version contains certain drivers that contain code encumbered under NDA. There are three source packages released by 4Front Technologies: * GPL version contains the source code for Linux * CDDL version contains the source code for Solaris * BSD version contains the source code for FreeBSD (and other BSD OSs) 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 commercial OSS package with rest of the software compiled from open source OSS sources because certain header 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. Build system requirements ------------------------- To be able to extract the source files from the tarball you will need 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 Solaris/OpenSolaris 10 or later x86, amd64, Sparc (64 bit) Linux 2.6 or later x86, x86_64 FreeBSD 6 or later x86, x86_64 SCO UnixWare 7 or later x86 SCO OpenServer 6 or later x86 Note that the very latest kernel versions may not be supported out of box. Changes may be needed to OSS before it supports them. 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). The stock make command shipped with some operating systems (SCO UnixWare and OpenServer) is not capable to compile OSS. In such systems you will have to install GNU make and use it instead. The make utilities shipped with Linux, Solaris and FreeBSD are OK. GTK 1.2 or GTK 2.0 development libraries must also be installed for the GUI apps like ossxmix. GTK 2.0 must be installed and registered via pkgconfig or GTK-1.2 must be installed and gtk-config must be there in the path. 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. - C compiler (gcc or cc) - make (gmake or make) - GNU binutils (ld, as) - GNU awk (gawk) - Standard C library (libc/glibc) headers. - GTK+ (either v1.2 or v2.0) 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 from 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. Its contents are distributed in the source tarball (oss-v4.2-build2004-src-bsd.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 is 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.2-build2004-src-bsd.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.2-build2004-src-bsd.tar.bz2 | tar xvf - (Or if you have GNU make (Linux, FreeBSD) you simply use tar xvfj /tmp/oss-v4.2-build2004-src-bsd.tar.bz2). After restoring the files they will appear in the oss-v4.2-build2004-src-bsd subdirectory under the current directory. Note! bunzip2 command is part of the bzip2 package. Compiling obsolete drivers -------------------------- Drivers for few sound cards are no longer actively maintained and they will not be compiled by default. These devices have been out of production for about 10 years and we don't expect that anybody has them any more: oss_allegro oss_als3xx oss_als4k oss_digi32 oss_maestro oss_neomagic oss_s3vibes oss_vortex The above drivers are located in the attic/drv subdirectory and they will not get compiled by default. However you can compile any of them after creating a symbolic link (this needs to be done in the source directory before running the configure script. For example if you would like to compile the oss_digi32 driver then you can do the following: cd kernel/drv ln -s ../../attic/drv/oss_digi32 . 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.2-build2004 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). NOTE! THE BUILD DIRECTORY MUST BE OUTSIDE THE SOURCE DIRECTORY. Otherwise the configure script will go to endless loop and fail. You need to give absolute path to the source directory when running configure. Relative paths (such as ../$TARGETDIR/configure) will not work properly. 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 OpenServer 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. Command line arguments of the configure script ---------------------------------------------- In most cases you should execute the configure script without any command line arguments. The following switches are available but they are mostly untested and should only be used in special situations. --regparm --no-regparm These switches are only defined for Linux. They control if OSS is to be built for a kernel compiled with or without the CONFIG_REGPARM setting. By default OSS drivers will be compiled for both alternatives and the right one will be selected automatically when OSS is installed. --target=uclinux-blackfin Experimental an incompletely implemented hack for cross compiling OSS for uClinux/Blackfin. Do not use. --copy-files By default the configure script will create symbolic links from the build directory to the original files in the source directory. This switch can be used to force copying of files instead of linking. This will result in multiple copies of the same file in the source tree (under Linux and Solaris/x86). For this reason this switch should not be used. --config-vmix=FLOAT | FIXEDPOINT | NO By default the virtual mixer (vmix) subsystem will be enabled. Depending on the target operating system it will use floating point (Linux) or fixed point arithmetic. This command line switch can be used to disable vmix (NO) or to enforce fixed point (FIXEDPOINT). Note that floating point is not supported under other that x86/x86_64 processors. Also some operating systems don't support it. --config-midi=NO|YES By default (in OSS v4.1) MIDI support is disabled. If you like to do hacking with MIDI you can enable it by using --config-midi=YES. 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.2-build2004-src-bsd.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.