﻿// This file is in AsciiDoc format. It is converted to README.html.

Using asapconv
--------------

Run the program from the command line to see the syntax.
The `-o`/`--output` option selects the output format and is mandatory.


Using libasap
-------------

The library is documented in the `asap.h` header file.
Be warned there might be breaking changes in the future versions of the library.


Compilation instructions
------------------------

Required tools
~~~~~~~~~~~~~~

For all builds you will need:

GNU Make::
On Linux this program is called `make`. On other systems it may be called `gmake`
(if this is the case, type `gmake` instead of `make` in the following instructions).
On Windows you may install GNU Make from http://cygwin.com/[Cygwin] or http://www.mingw.org/[MinGW].

Standard Unix tools::
I mean `sh`, `cat`, `cp`, `rm`, `mkdir`. On Windows you can find them in Cygwin.

xasm and MADS::
If you are compiling latest source code from Git, install
http://xasm.atari.org/[xasm] and http://mads.atari8.info/[MADS].

Ć Translator::
The core of ASAP is written in the Ć programming language.
You'll need http://cito.sourceforge.net[cito].
For your convenience, this is not needed for most of the C and C++ ports.

Make sure these tools are on your `PATH`.


Getting officially released source code
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you want to compile an official release of ASAP, download a source distribution
(`asap-*.tar.gz`) and uncompress it to a directory of your choice.

On Unix-like systems:
--------------------------------------------------------------------------------
tar zxf asap-*.tar.gz
--------------------------------------------------------------------------------

On Windows you may use http://7-zip.org/[7-Zip].


Getting latest source code
~~~~~~~~~~~~~~~~~~~~~~~~~~

Alternatively you may get the latest version from the Git repository.
To do this using a command-line Git client:
--------------------------------------------------------------------------------
git clone git://asap.git.sourceforge.net/gitroot/asap/asap
--------------------------------------------------------------------------------

This will fetch the latest code into a new directory called `asap`.


Building asapconv and libasap on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From your shell prompt navigate to the directory which contains `asap.c`.

To compile and install, run the following commands:
--------------------------------------------------------------------------------
make
sudo make install
--------------------------------------------------------------------------------

The latter command installs the command-line converter and the C library
in `/usr/local`.


Building the Audacious plugin on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install `audacious-devel`.
To compile, run the following command:
--------------------------------------------------------------------------------
make asap-audacious
--------------------------------------------------------------------------------

To install in `/usr/lib/audacious/Input`:
--------------------------------------------------------------------------------
sudo make install-audacious
--------------------------------------------------------------------------------


Building the GStreamer plugin on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To compile, run the following command:
--------------------------------------------------------------------------------
make asap-gstreamer
--------------------------------------------------------------------------------

To install in `/usr/lib/gstreamer-0.10`:
--------------------------------------------------------------------------------
sudo make install-gstreamer
--------------------------------------------------------------------------------


Building the MOC plugin on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need source code of MOC. The plugin is compatible with MOC 2.4.x
and MOC 2.5.0 alpha.

Check `MOC_INCLUDE` and `MOC_PLUGIN_DIR` in the `moc/moc.mk` file.
These should be the directory with MOC sources
and the directory with the installed MOC plugins, respectively.

If the defaults are correct, use the following commands:
--------------------------------------------------------------------------------
make asap-moc
sudo make install-moc
--------------------------------------------------------------------------------

If you need to specify different directories, use:
--------------------------------------------------------------------------------
make asap-moc MOC_INCLUDE=path/to/moc/sources
sudo make install-moc MOC_PLUGIN_DIR=/path/to/moc/plugins
--------------------------------------------------------------------------------


Building the VLC plugin on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install `vlc-devel`. Verify paths at the top of `vlc/vlc.mk`.
To compile, run the following command:
--------------------------------------------------------------------------------
make asap-vlc
--------------------------------------------------------------------------------

To install:
--------------------------------------------------------------------------------
sudo make install-vlc
--------------------------------------------------------------------------------


Building the XBMC plugin on Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need source code of the Linux port of XBMC.

Run:
--------------------------------------------------------------------------------
make asap-xbmc XBMC_DLL_LOADER_EXPORTS=path/to/dir/in/xbmc/sources
--------------------------------------------------------------------------------

`XBMC_DLL_LOADER_EXPORTS` must point to the directory in XBMC sources
which contains `wrapper.def` and `wrapper.o`.
You should get `xbmc_asap-i486-linux.so`.

Recently I wasn't able to enable the ASAP plugin in XBMC.
This seems to be an XBMC issue.


Building the XMMS plugin on Unix-like systems
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need `xmms` and `xmms-devel` packages.

To compile, run the following command:
--------------------------------------------------------------------------------
make asap-xmms
--------------------------------------------------------------------------------

If the compilation finished successfully, you can install the plugin
in your home directory:
--------------------------------------------------------------------------------
make install-xmms-user
--------------------------------------------------------------------------------

or for all users:
--------------------------------------------------------------------------------
sudo make install-xmms
--------------------------------------------------------------------------------

If you have another XMMS plugin that supports Atari 8-bit music,
remove it in order to avoid conflicts.


Building asapconv, WASAP, Winamp/GSPlayer/Apollo/XMPlay/BASS plugins, RMT DLL, asapscan, shell extension and libasap on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install the C and C++ compilers from http://www.mingw.org/[MinGW].

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make mingw
--------------------------------------------------------------------------------

You should get `asapconv.exe`, `wasap.exe`, `in_asap.dll`, `gspasap.dll`,
`ASAP_Apollo.dll`, `xmp-asap.dll`, `bass_asap.dll`, `apokeysnd.dll`,
`asapscan.exe`, `ASAPShellEx.dll` and `libasap.a`.


Building Windows Media Player plugin and asap.lib on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You additionally need Windows SDK
(install native C++ compiler, headers, libraries and samples).
Set `Path`, `INCLUDE` and `LIB` environment variables
to point to the right locations in the Windows SDK.
Make sure `DSHOW_BASECLASSES_DIR` is set correctly in `win32\win32.mk`.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make win32/asap_dsf.dll win32/asap.lib
--------------------------------------------------------------------------------

You will get `asap_dsf.dll` and `asap.lib`.


Building the GStreamer plugin on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install http://www.gstreamer.com/[GStreamer SDK] 32-bit development files.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make win32/libgstasapdec.dll
--------------------------------------------------------------------------------

Building the Audacious plugin on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Too bad Audacious doesn't provide an SDK for Windows.

Unpack http://ftp.gnome.org/pub/gnome/binaries/win32/gtk+/2.24/gtk+-bundle_2.24.10-20120208_win32.zip[GTK+ 2 bundle]
and make sure `GTK_DIR` in `win32/win32.mk` points to it.

Install Audacious and make sure `AUDACIOUS_LIB` points inside it.

Unpack Audacious source code and make sure `AUDACIOUS_INCLUDE` points inside it.

Now comes the tricky part: configure Audacious for Windows.
You'll need to install `gettext` and `libgnurx` in MinGW
(that's probably not an exhaustive list, `configure` will complain about missing things).
From the Audacious source directory run:
--------------------------------------------------------------------------------
bash configure PKG_CONFIG=../gtk/bin/pkg-config
--------------------------------------------------------------------------------

After it finishes with no errors (warnings are fine), go to ASAP and run:
--------------------------------------------------------------------------------
make win32/asapplug.dll
--------------------------------------------------------------------------------

Put the DLL in `lib/audacious/Input` of the Windows binary distribution of Audacious.


Building the foobar2000 plugin on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to the common prerequisites and Windows SDK you need
foobar2000 SDK - extract it to a new directory called
`foobar2000_SDK` next to (not inside!) the ASAP directory.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make win32/foo_asap.dll
--------------------------------------------------------------------------------

This should produce `foo_asap.dll`.


Building the VLC plugin on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install VLC as usual, it includes the SDK.
`VLC_SDK_DIR` in `win32/win32.mk` is fine for the default installation
directory on 64-bit Windows - edit it if necessary.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make win32/libasap_plugin.dll
--------------------------------------------------------------------------------

You will get `libasap_plugin.dll`.


Building the XBMC plugin on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need Visual C\++ Toolkit (it used to be a free download from Microsoft,
now search the internet for `VCToolkitSetup.exe`)
and .NET Framework SDK Version 1.1.
Microsoft Visual C++ 2003 might work, but wasn't tested.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make win32/xbmc_asap.dll
--------------------------------------------------------------------------------

This should produce `xbmc_asap.dll`, which you can use with XBox
or Windows version of XBMC. The XBMC must include support for ASAP.

Alternatively, you may use the `build_vctk.bat` script in the `xbmc` directory.


Building WASAP, GSPlayer and Windows Media Player plugins for Windows CE
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For WASAP and GSPlayer plugins you need http://cegcc.sourceforge.net/[CeGCC].
For the Windows Media Player plugin you need Visual Studio 2008
(2005 might work, but wasn't checked, 2010 won't work).

Edit the `WINCE_...` paths at the top of `win32/win32.mk` so that they point to your installed tools.
Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make wince
--------------------------------------------------------------------------------

This should produce `wasap.exe`, `gspasap.dll` and `asap_dsf.dll`
in the `win32/wince` directory.


Building Java ASAP2WAV and Java applet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need Java Development Kit (JDK).

If necessary, edit the paths at the top of `java/java.mk` so that they point to your installed tools.
Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make java/asap2wav.jar java/asap_applet.jar
--------------------------------------------------------------------------------

This should produce `asap2wav.jar` and `asap_applet.jar`.


Building Java midlet
~~~~~~~~~~~~~~~~~~~~

You need a Java ME SDK - I use Oracle Java ME SDK.

Edit the WTK path at the top of `java/j2me/j2me.mk` so that they point to your installed Java ME SDK.
Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make java/j2me/asap_midlet.jad
--------------------------------------------------------------------------------

This should produce `asap_midlet.jar` and `asap_midlet.jad`.


Building AndroidASAP
~~~~~~~~~~~~~~~~~~~~

Install http://developer.android.com/sdk/[Android SDK]
with an Android platform(s) (I compile with 2.2 and test with 1.6).

Edit the paths at the top of `java/android/android.mk` so that they point to your installed SDK.
Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make android-debug
--------------------------------------------------------------------------------

This should produce `AndroidASAP-debug.apk`.
AndroidASAP integrates with file managers and the web browser.
It uses the internet connection only for files clicked in the web browser.


Building C# ASAP2WAV, asapplay and SilverASAP on Windows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need the .NET Framework, of course.
For SilverASAP you need Silverlight and 7-Zip.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make csharp
--------------------------------------------------------------------------------

This should produce `asap2wav.exe`, `asapplay.exe` and `SilverASAP.xap`.


Building MetroASAP for Windows 8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

NOTE: Windows 8 is not yet generally available and this port is work in progress.

Install .NET Framework 4.5 (Windows 8 already has it).
Install Windows SDK for Windows 8 or Visual Studio 2012 (any edition should be fine).
Verify the paths at the top of `csharp/winrt/winrt.mk`.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make csharp/winrt/MetroASAP.appx
--------------------------------------------------------------------------------

If you're not on Windows 8, the last step (creating the appx) will fail,
but you'll have the application in the `csharp/winrt/obj` directory.
Copy it to Windows 8 and install from PowerShell:
--------------------------------------------------------------------------------
Add-AppxPackage AppxManifest.xml -Register
--------------------------------------------------------------------------------


Building JavaScript command-line ASAP2WAV and the web browser player
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make javascript
--------------------------------------------------------------------------------

`asap2wav.js` is the command-line script.
`asapweb.js` plus `asap.js` are the browser player (you'll probably need `binaryHttpRequest.js` as well).


Building Flash player version of ASAP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need http://opensource.adobe.com/wiki/display/flexsdk/Flex+SDK[Flex SDK].
Add its `bin` directory to your `PATH`.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make flash/asap.swf
--------------------------------------------------------------------------------

You should get `asap.swf`.


Building D ASAP2WAV and asapplay on Windows and Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You need DMD 2.054 or compatible D compiler.
To build asapplay on Windows, you need http://www.dsource.org/projects/bindings/wiki/WindowsApi[D Windows API bindings].
On Linux, you need ALSA development libraries (e.g. libasound2-dev package in Ubuntu).
D bindings for ALSA are currently included in ASAP sources.

Open the command prompt in the root directory of ASAP sources and run:
--------------------------------------------------------------------------------
make d
--------------------------------------------------------------------------------

This should produce `asap2wav.exe` and `asapplay.exe`.

