PM123 1.34 Source File Distribution

Copyright 1997-2003 Samuel Audet <guardia@step.polymtl.ca>
                    Taneli Lepp„ <rosmo@sektori.com>
Copyright 2004-2012 Dmitry A.Steklenev <glass@ptv.ru>

Introduction
============

In this small README file, you will learn how to use this source file
distribution to successfully compile PM123 from the sources.

Tools Needed to Compile
=======================

You will need the following tools and libraries to compile PM123
via IBM VisualAge C++:

  VisualAge C++ 3.6 fixpak 2
  A recent IBM OS/2 Developer's Toolkit
  NASM (recent versions of NASM can produce non-working mpg123 module, 
  therefore NASM 0.98.38 is recommended)
  WarpIN (if you want to create an installation package)
  Info-ZIP (if you want to create the ZIP package)

You will need the following tools and libraries to compile PM123 via
Open Watcom C++:

  Open Watcom C++ 1.9
  NASM
  Operating System/2 Information Presentation Facility Compiler (included in to
  IBM OS/2 Developer's Toolkit).
  WarpIN (if you want to create an installation package)
  Info-ZIP (if you want to create the ZIP package)

Also, I have been using cmd.exe at all times, so disable 4os2 or other cmd.exe
replacement when using this distribution's makefiles.

Directory Structure
===================

The directories are split as shown in the diagram below. "dist" contains the
files needed to build the install packages, and the packages themselves once
they are built. "doc" contains text files and the user manual in HTML format.
"extra" contains files that are not part of pm123 per se. "pdk" (plug-in
developer's kit) documentation to build new plug-ins. "src" contains all
the source code of PM123.

|
+dist
|   |
|   +files
+doc
|   |
|   +manual
|   +pdk
|   +tools
+extra
|   |
|   +irc
|   +slider
+src
|   |
|   +config
|   +fft123
|   +gbm123
|   +include
|   +main
|   +ogg123
|   +plug-ins
|   |   |
|   |   +analyzer
|   |   +cddaplay
|   |   +flacplay
|   |   +macplay
|   |   +mpg123
|   |   +oggplay
|   |   +os2audio
|   |   +realeq
|   |   +wavout
|   |   +wavplay
|   |
|   +pm123
|   +skinutil
|   +snd123
|   +utils
|   +vrb123
|   +WPS
|   +xio123
|   +zlb123

In the "extra" directory, there "irc" has some scripts for BitchX and ircii
to display the playing songs in the IRC client window. "slider" is a small
tool that uses PM123's pipe to control the volume of two instances of PM123.
The volume of the first PM123 executed will follow the slider, and the
second will go reverse, allowing to cross the sounds of two songs for DJs.

In the "src" directory, all the source code of one module (one EXE or DLL)
is found in a subdirectory of the same name as the module.  So pm123.dll's
source code is found in "pm123" and realeq.dll's source code is found under
"plug-ins\realeq".  Each directory has its own makefile, fully functional.
Two exceptions.  First, "utils" is the home of an internal utility library
named utilfct.lib. Finally, the "include" directory only contains ".h" files.

Description of modules
----------------------

fft123
   The FFT algorithm used by analyzer.dll (through pm123.exe) and realeq.dll.
gbm123
   The Generalized Bitmap Module used by PM123 and skinutil.exe for loading
   and creating bitmaps for skins.
ogg123
   The Ogg bitstream format library used by oggplay.dll.
vrb123
   The Vorbis library used by oggplay.dll.
snd123
   The library of C routines for reading and writing files containing sampled
   audio data. Used by wavplay.dll.
xio123
   Input/output engine. Used by PM123 and plug-ins.
zlb123
   The general purpose data compression library.
analyzer
   The spectrum analyzer visual plug-in.
cddaplay
   The CD Player with CDDB support.
mpg123
   The MP3 decoder with streaming support.
oggplay
   The Ogg Vorbis decoder with streaming support.
flacplay
   The FLAC decoder with streaming support.
macplay
   The Monkey's audio decoder with streaming support.
os2audio
   The output plug-in that uses DART to access the sound card.
realeq
   The Real Equalizer plug-in, with MMX support and all.
wavout
   The output plug-in that dumps everything in a WAV file.
wavplay
   The WAV file player.
main
   The main pm123.exe.
pm123
   The main pm123.dll which includes all the GUI stuff and skin support.
skinutil
   skinutil.exe to convert WinAmp 1.x skins and manage skins.

How to Compile
==============

You can use the following commands with the main makefile and NMAKE:

all:         will compile EVERYTHING in "src"
filename:    will compile that module (ie.: "pm123.exe", "analyzer.dll", etc)
clean:       will clean up all the compiled binaries in "src"
dist:        will do "distfiles", "distpackage" and "distzip"
distfiles:   will copy all the needed binaries and files from "src", "doc" and
             others into "dist\files"
distpackage: will build the WarpIN packages from the files in "dist\files"
distzip:     will build the ZIP file from the files in "dist\files"
distclean:   will clean everything made by "dist"

You can also use all of the individual makefiles in each of the subdirectories
of the "src" directory. Each of them contain an "all" and "clean" command.

In all cases, you can add "DEBUG=1" to MAKE's command line to build
a debug version of one of PM123's module. Example:

   [c:\devel\pm123-1_2-src] nmake pm123.exe DEBUG=1

Also you can add "TCP40=1" to MAKE's command line to build modules with
TCP/IP v4.0 (16bit) support. Example:

   [c:\devel\pm123-1_2-src] nmake all TCP40=1

Have fun!

Samuel Audet and Taneli Lepp„
September 2003
Dmitry A.Steklenev
May 2012
