path: root/README.md

README
======


OpenMPT and libopenmpt
======================

This repository contains OpenMPT, a free Windows/Wine-based
[tracker](https://en.wikipedia.org/wiki/Music_tracker) and libopenmpt,
a library to render tracker music (MOD, XM, S3M, IT MPTM and dozens of other
legacy formats) to a PCM audio stream. libopenmpt is directly based on OpenMPT,
offering the same playback quality and format support, and development of the
two happens in parallel.


License
-------

The OpenMPT/libopenmpt project is distributed under the *BSD-3-Clause* License.
See [LICENSE](LICENSE) for the full license text.

Files below the `include/` (external projects) and `contrib/` (related assets
not directly considered integral part of the project) folders may be subject to
other licenses. See the respective subfolders for license information. These
folders are not distributed in all source packages, and in particular they are
not distributed in the Autotools packages.


How to compile
--------------


### OpenMPT

 -  Supported Visual Studio versions:

     -  Visual Studio 2015 Update 3 Community/Professional/Enterprise

        To compile the project, open `build/vs2015/OpenMPT.sln` and hit the
        compile button.

     -  Visual Studio 2017 Community/Professional/Enterprise

        To compile the project, open `build/vs2017/OpenMPT.sln` and hit the
        compile button.

 -  OpenMPT requires the compile host system to be 64bit x86-64.

 -  The Windows 8.1 SDK and Microsoft Foundation Classes (MFC) are required to
    build OpenMPT (both are included with Visual Studio, however may need to be
    selected explicitly during setup). In order to build OpenMPT for Windows XP,
    the XP targetting toolset also needs to be installed.

 -  The ASIO SDK is needed for compiling with ASIO support.

    If you don't want this, comment out `#define MPT_WITH_ASIO` in the file
    `common/BuildSettings.h`.

    The ASIO SDK can be downloaded automatically on Windows 7 or later by just
    running the `build/download_externals.cmd` script.

    If you do not want to or cannot use this script, you may follow these manual
    steps instead:

     -  Visit
        [steinberg.net](https://www.steinberg.net/en/company/developers.html) to
        download the SDK.

     -  Put the ASIO SDK in the `include/ASIOSDK2` folder. The top level
        directory of the SDK is already named `ASIOSDK2`, so simply move that
        directory in the include folder.

    If you need further help with the ASIO SDK, get in touch with the
    main OpenMPT developers. 


### libopenmpt and openmpt123

For detailed requirements, see `libopenmpt/dox/quickstart.md`.

 -  Autotools

    Grab a `libopenmpt-VERSION-autotools.tar.gz` tarball.

        ./configure
        make
        make check
        sudo make install

    Cross-compilation is generally supported (although only tested for
    targetting MinGW-w64).

    Note that some MinGW-w64 distributions come with the `win32` threading model
    enabled by default instead of the `posix` threading model. The `win32`
    threading model lacks proper support for C++11 `<thread>` and `<mutex>` as
    well as thread-safe magic statics. It is recommended to use the `posix`
    threading model for libopenmpt for this reason. On Debian, the appropriate
    configure command is
    `./configure --host=x86_64-w64-mingw32 CC=x86_64-w64-mingw32-gcc-posix CXX=x86_64-w64-mingw32-g++-posix`
    for 64bit, or
    `./configure --host=i686-w64-mingw32 CC=i686-w64-mingw32-gcc-posix CXX=i686-w64-mingw32-g++-posix`
    for 32bit. Other MinGW-w64 distributions may differ.

 -  Visual Studio:

     -  You will find solutions for Visual Studio 2015 to 2017 in the
        corresponding `build/vsVERSION/` folder.
        Projects that target Windows versions before Windows 7 are available in
        `build/vsVERSIONxp/`.
        Projects that target Windows 10 1709 Desktop (10.0.16299.0, including
        ARM and ARM64) or later versions are available in
        `build/vsVERSIONwin10/`.
        Minimal projects that target Windows 10 UWP are available in
        `build/winstore82/`.
        Most projects are supported with any of the mentioned Visual Studio
        verions, with the following exceptions:

         -  in_openmpt: Requires Visual Studio with MFC.

         -  xmp-openmpt: Requires Visual Studio with MFC.

     -  libopenmpt requires the compile host system to be 64bit x86-64 when
        building with Visual Studio.

     -  You will need the Winamp 5 SDK and the XMPlay SDK if you want to
        compile the plugins for these 2 players. They can be downloaded
        automatically on Windows 7 or later by just running the
        `build/download_externals.cmd` script.

        If you do not want to or cannot use this script, you may follow these
        manual steps instead:

         -  Winamp 5 SDK:

            To build libopenmpt as a winamp input plugin, copy the contents of
            `WA5.55_SDK.exe` to include/winamp/.

            Please visit
            [winamp.com](http://wiki.winamp.com/wiki/Plug-in_Developer) to
            download the SDK.
            You can disable in_openmpt in the solution configuration.

         -  XMPlay SDK:

            To build libopenmpt with XMPlay input plugin support, copy the
            contents of xmp-sdk.zip into include/xmplay/.

            Please visit [un4seen.com](https://www.un4seen.com/xmplay.html) to
            download the SDK.
            You can disable xmp-openmpt in the solution configuration.

 -  Makefile

    The makefile supports different build environments and targets via the
    `CONFIG=` parameter directly to the make invocation.
    Use `make CONFIG=$newconfig clean` when switching between different configs
    because the makefile cleans only intermediates and target that are active
    for the current config and no configuration state is kept around across
    invocations.

     -  mingw-w64:

        The required version is at least 4.8.

            make CONFIG=mingw64-win32    # for win32

            make CONFIG=mingw64-win64    # for win64

     -  gcc or clang (on Unix-like systems, including Mac OS X with MacPorts,
        and Haiku (32-bit Hybrid and 64-bit)):

        The minimum required compiler versions are:

         -  gcc 4.8

         -  clang 3.6

        The Makefile requires pkg-config for native builds.
        For sound output in openmpt123, PortAudio or SDL is required.
        openmpt123 can optionally use libflac and libsndfile to render PCM
        files to disk.

        When using gcc, run:

            make CONFIG=gcc

        When using clang, it is recommended to do:

            make CONFIG=clang

        Otherwise, simply run

            make

        which will try to guess the compiler based on your operating system.

     -  emscripten (on Unix-like systems):

        libopenmpt has been tested and verified to work with emscripten 1.38.5
        or later. Earlier versions are not supported.

        Run:

            # generates WebAssembly with dynamic heap growth
            make CONFIG=emscripten EMSCRIPTEN_TARGET=wasm

        or

            # generates asm.js with a fixed size 128MB heap
            make CONFIG=emscripten EMSCRIPTEN_TARGET=asmjs128m

        or

            # generates asm.js with a fixed default size heap (as of Emscripten
            # 1.38.11, this amounts to 16MB)
            make CONFIG=emscripten EMSCRIPTEN_TARGET=asmjs

        or

            # generates JavaScript with dynamic heap growth and with
            # compatibility for older VMs
            make CONFIG=emscripten EMSCRIPTEN_TARGET=js

        Running the test suite on the command line is also supported by using
        node.js. Version 8.9.1 or greater has been tested. Earlier versions
        might or might not work. Depending on how your distribution calls the
        `node.js` binary, you might have to edit
        `build/make/config-emscripten.mk`.

     -  DJGPP / DOS

        Cross-compilation from Linux systems is supported with DJGPP GCC 7.2 or
        later via

            make CONFIG=djgpp

        `openmpt123` can use liballegro 4.2 for sound output on DJGPP/DOS.
        liballegro can either be installed system-wide in the DJGPP environment
        or downloaded into the `libopenmpt` source tree.

            make CONFIG=djgpp USE_ALLEGRO42=1    # use installed liballegro

        or

            ./build/download_externals.sh    # download liballegro binaries
            make CONFIG=djgpp USE_ALLEGRO42=1 BUNDLED_ALLEGRO42=1

     -  American Fuzzy Lop:

        To compile libopenmpt with fuzzing instrumentation for afl-fuzz, run:
        
            make CONFIG=afl
        
        For more detailed instructions, read `contrib/fuzzing/readme.md`.

     -  other compilers:

        To compile libopenmpt with other C++11 compliant compilers, run:
        
            make CONFIG=generic
        
    
    The `Makefile` supports some customizations. You might want to read the top
    which should get you some possible make settings, like e.g.
    `make DYNLINK=0` or similar. Cross compiling or different compiler would
    best be implemented via new `config-*.mk` files.

    The `Makefile` also supports building doxygen documentation by using

        make doc

    Binaries and documentation can be installed systen-wide with

        make PREFIX=/yourprefix install
        make PREFIX=/yourprefix install-doc

    Some systems (i.e. Linux) require running

        sudo ldconfig

    in order for the system linker to be able to pick up newly installed
    libraries.

    `PREFIX` defaults to `/usr/local`. A `DESTDIR=` parameter is also
    supported.

 -  Android NDK

    See `build/android_ndk/README.AndroidNDK.txt`.



Contributing to OpenMPT/libopenmpt
----------------------------------


See [contributing](doc/contributing.md).