Skip to content

Commit

Permalink
Updated some documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
@icculus
icculus committed Jul 20, 2018
1 parent ee35bef commit c74024a
Show file tree
Hide file tree
Showing 3 changed files with 62 additions and 113 deletions.
124 changes: 41 additions & 83 deletions docs/INSTALL.txt
View file
@@ -1,104 +1,62 @@
Building is pretty easy. Please read README, too, as it duplicates and
expands upon much of this information.
HOW TO BUILD SDL_SOUND 2.x ...

The 1.x branch of SDL_sound was pretty complicated to build, needing you to
hunt down external libraries and poke through various incompatible project
files. We've simplified this as much as possible for SDL2_sound. Now there are
no external libraries (everything is built internally, either with source
code we wrote or public domain code included with this project, and CMake
manages building.

ALL PLATFORMS:
The only external library SDL2_sound needs is SDL2. We assume you are using
SDL2 already if you've come looking for this library. It can be found at
https://www.libsdl.org/

Please understand your rights and mine: read the text file LICENSE.txt in the
root of the source tree. If you can't abide by it, delete this source tree now.

The best documentation for the SDL_sound API is SDL_sound.h. It is VERY
heavily commented, and makes an excellent, in-depth reference to all the
functions. The official API reference is generated from this file with
a program called "Doxygen" (http://www.doxygen.org/)
THE USUAL WAY (using CMake)...

To build SDL_sound, you'll need to install CMake ( https://cmake.org/ ) and
point it at the CMakeLists.txt file in SDL_sound's root directory. How you
do this varies by platform, but generally you either get it right from
cmake.org or from your platform's usual means of software installation.

Borland C++ Builder for Linux (Kylix 3):
Unzip the "borland.zip" file in the root of the source tree and use the
project files in the newly-created Borland/k3 directory. Makefiles for the
command line compiler are in Borland/freebcc ...
Generally the defaults are fine, which are to build everything it can. If
you _really_ want to disable some piece of SDL_sound, like the .voc decoder,
you can use CMake to toggle that option.

CMake will generate project files for whatever compiler you happen to have.

Unix:
(If you pulled the source from CVS), run ./bootstrap

run ./configure --help, and see if there's any options you need. Rerun
configure with those options. If this is confusing to you, just run
./configure with no options: the defaults are generally decent, and
configure is usually smart enough to figure out what's best..
WAIT THAT'S STILL TOO COMPLEX...

If configuration succeeded, run "make".
Don't want to use CMake? Everything in SDL_sound is either zlib-licensed or
public domain, which means you can just copy it into your own project and
compile it directly, instead of messing with it as an external library. There
are no restrictions on doing this, even if you're writing commercial,
closed-source software.

Run "make install" as root to install the library for use on your system.
This assumes you are already using SDL2, which SDL_sound relies on. If
not, you'll need to make sure SDL's header's are available and we can link
against the SDL library.

This should work for most Unix-style systems, including Linux, *BSD, BeOS, and
MacOS X. Reports of success and failure are welcome.
To do this:
- Add everything in the src directory to your project (including the C files
in the libmikmod directory).
- Make sure your app can see SDL_sound.h to #include it.
- That's all. You don't have to #define anything, etc.


MacOS 9 users:
Included with the source is CWProject.sit, which contains project files for
CodeWarrior 5.0 and later.
PLAYSOUND...

Is an optional test application. If you can compile and link
playsound/playsound_simple.c, then you know everything is set up correctly.
This is a separate program that uses SDL_sound, and shouldn't be compiled
into the library itself.

MacOS X command line tools:
You can use the "UNIX" instructions above if you like the command line tools.

OTHER NOTES...

MacOS X Project Builder:
If you prefer to use Project Builder, use the project files included with
this source: PBProjects.tar.gz...unpack it in the root of the SDL_sound
folder. This archive contains several external libraries you would have
to download/install manually if you used the command line tools (these
libraries are for extra decoders, and are NOT required for SDL_sound to
function...however, without them, the number of sound formats you can
decode is reduced.)


BeOS:
You can use the "UNIX" instructions above, too.


Win32 Visual C:
For Visual C, use:
http://icculus.org/SDL_sound/downloads/sdl_sound_visualc_srcs.zip
...and unzip it somewhere. This zipfile has a complete copy of the
SDL_sound sources, Visual C project files, and several external libraries,
too. This zip is everything you should need, and you can scrap this copy of
the source.


Win32 Cygwin:
Cygwin users can try their luck with the Unix build instructions in this
tarball instead.


Win32 Borland C++ Builder 6:
Unzip the "borland.zip" file in the root of the source tree and use the
project files in the newly-created Borland/bcb6 directory. Makefiles for the
command line compiler are in Borland/freebcc ... these are unmaintained, and
you will need to go find the external libraries you want to use (those that
wish to maintain these project files should contact me).


If building is successful, there will be a shared library and a binary
called "playsound".


Windows CE (Microsoft PocketPC):
You'll need Microsoft's PocketPC development environment, and this zipfile:
http://icculus.org/SDL_sound/downloads/SDL_soundCE.zip

Unzip that into the root of this source tree. The new "wce" directory has
project files, and the source to some of the external decoders is included.
Note that not all of the decoders are supported on PocketPC (but please, do
send us patches if you get them working!)


OTHER PLATFORMS:

Send me patches, and instructions, and I'll list them here. Consider
joining the SDL_sound mailing list. Details are at:
http://icculus.org/SDL_sound/
Questions? Problems? Patches? Consider joining the SDL_sound mailing list.
Details are at https://icculus.org/SDL_sound/

--ryan. (icculus@icculus.org)

Expand Down
50 changes: 20 additions & 30 deletions docs/README.txt
View file
Expand Up @@ -12,41 +12,32 @@ SDL_sound is a library that handles the decoding of several popular sound file
desires.

Please check the website for the most up-to-date information about SDL_sound:
http://icculus.org/SDL_sound/
https://icculus.org/SDL_sound/

SDL_sound _REQUIRES_ Simple Directmedia Layer (SDL) to function, and cannot
be built without it. You can get SDL from http://www.libsdl.org/. SDL_sound
has only been tried with the SDL 1.2 series, but may work on older versions.
SDL_sound _REQUIRES_ Simple Directmedia Layer (SDL) 2.x to function, and cannot
be built without it. You can get SDL from https://www.libsdl.org/. SDL_sound
2.x only works with SDL2, and SDL_sound 1.x only works with SDL 1.x.
Reports of success or failure are welcome.

Some optional external libraries that SDL_sound can use and where to find them:
SMPEG (used to decode MP3s): http://icculus.org/smpeg/
libvorbisfile (used to decode OGGs): http://www.xiph.org/ogg/vorbis/
libSpeex (used to decode SPXs): http://speex.org/
libFLAC (used to decode FLACs): http://flac.sourceforge.net/
libModPlug (used to decode MODs, etc): http://modplug-xmms.sourceforge.net/
libMikMod (used to decode MODs, etc, too): http://www.mikmod.org/

Experimental QuickTime support for the Mac is included, but has not been
integrated with the build system, and probably doesn't work with
QuickTime for Windows.

These external libraries are OPTIONAL. SDL_sound will build and function
without them, but various sound file formats are not supported unless these
libraries are available. Unless explicitly disabled during initial build
configuration, SDL_sound always supports these file formats internally:

- Microsoft .WAV files (uncompressed and MS-ADPCM encoded).
- Creative Labs .VOC files
Unless explicitly disabled during initial build configuration, SDL_sound
always supports these file formats internally:

- Wave (.WAV) files
- MPEG-1 layers I-III (.MP3, .MP2, .MP1)
- Ogg Vorbis (.OGG) files
- Free Lossless Audio Codec (.FLAC) files
- Audio Interchange format (.AIFF) files
- Sun/NeXT Audio (.AU) files
- Shorten (.SHN) files
- Audio Interchange format (AIFF) files
- Sun Audio (.AU) files
- MIDI files
- MP3 files (internal decoder, different than the one SMPEG uses)
- Raw waveform data
- Creative Labs Voice (.VOC) files
- Various "module" formats (.MOD, .669, .AMF, .XM, .IT, .S3M, .STM, etc)
- MIDI (.mid) files
- ABC (.abc) files
- Raw PCM data
- (macOS/iOS only) anything that CoreAudio can decode.

Building/Installing:
Please read the INSTALL document.
Please read the docs/INSTALL.txt document.

Reporting bugs/commenting:
There is a mailing list available. Subscription and mailing list archives
Expand All @@ -58,4 +49,3 @@ Reporting bugs/commenting:

--ryan. (icculus@icculus.org)


1 change: 1 addition & 0 deletions docs/TODO.txt
View file
Expand Up @@ -2,6 +2,7 @@ More immediate:
- Fix the crappy rewind implementation in shn.c's SHN_rewind().
- Finish implementing seek() method in decoders, see below.
- Make sure we can build shared libs on Cygwin, BeOS, Mac OS X...
- Add a buildbot

Decoders still needing seek() method:
(If decoder can't seek, clean up the stub and report an error.)
Expand Down

0 comments on commit c74024a

Please sign in to comment.