Initial community commit
This commit is contained in:
Jef
parent
537bcbc862
commit
fc06254474
16440 changed files with 4239995 additions and 2 deletions
1087
Src/external_dependencies/openmpt-trunk/libopenmpt/dox/changelog.md
Normal file
1087
Src/external_dependencies/openmpt-trunk/libopenmpt/dox/changelog.md
Normal file
File diff suppressed because it is too large
Load diff
|
|
@ -0,0 +1,122 @@
|
|||
|
||||
Dependencies {#dependencies}
|
||||
============
|
||||
|
||||
|
||||
Dependencies
|
||||
------------
|
||||
|
||||
### libopenmpt
|
||||
|
||||
* Supported compilers for building libopenmpt:
|
||||
* **Microsoft Visual Studio 2017** or higher, running on a amd64 build
|
||||
system (other target systems are supported)
|
||||
|
||||
Please note that we do not support building with a later Visual Studio
|
||||
installation with an earlier compiler version. This is because, while
|
||||
later Visual Studio versions allow installing earlier compilers to be
|
||||
available via the later version's environment, in this configuration,
|
||||
the earlier compiler will still use the later C and C++ runtime's
|
||||
headers and implementation, which significantly increases the matrix of
|
||||
possible configurations to test.
|
||||
|
||||
* **GCC 8.1** or higher
|
||||
* **Clang 7** or higher
|
||||
* **MinGW-W64 8.1** or higher (it is recommended to preferably use
|
||||
posix threading model as opposed to win32 threading model)
|
||||
* **emscripten 1.39.1** or higher
|
||||
* **DJGPP GCC 8.1** or higher
|
||||
* any other **C++17 compliant** compiler
|
||||
|
||||
libopenmpt makes the following assumptions about the C++ implementation
|
||||
used for building:
|
||||
* `std::numeric_limits<unsigned char>::digits == 8` (enforced by
|
||||
static_assert)
|
||||
* existence of `std::uintptr_t` (enforced by static_assert)
|
||||
* in C++20 mode, `std::endian::little != std::endian::big` (enforced
|
||||
by static_assert)
|
||||
* `wchar_t` encoding is either UTF-16 or UTF-32 (implicitly assumed)
|
||||
* representation of basic source character set is ASCII (implicitly
|
||||
assumed)
|
||||
* representation of basic source character set is identical in char
|
||||
and `wchar_t` (implicitly assumed)
|
||||
|
||||
libopenmpt does not rely on any specific implementation defined or
|
||||
undefined behaviour (if it does, that's a bug in libopenmpt). In
|
||||
particular:
|
||||
* `char` can be `signed` or `unsigned`
|
||||
* shifting signed values is implementation defined
|
||||
* `signed` integer overflow is undefined
|
||||
* `float` and `double` can be non-IEEE754
|
||||
|
||||
libopenmpt can optionally support certain incomplete C++
|
||||
implementations:
|
||||
* platforms without `wchar_t` support (like DJGPP)
|
||||
* platforms without working `std::random_device` (like Emscripten when
|
||||
running in `AudioWorkletProcessor` context)
|
||||
* platforms without working `std::high_resolution_clock` (like
|
||||
Emscripten when running in `AudioWorkletProcessor` context)
|
||||
|
||||
* Required compilers to use libopenmpt:
|
||||
* Any **C89** / **C99** / **C11** compatible compiler should work with
|
||||
the C API as long as a **C99** compatible **stdint.h** is available.
|
||||
* Any **C++17** compatible compiler should work with the C++ API.
|
||||
* **J2B** support requires an inflate (deflate decompression) implementation:
|
||||
* **zlib** (or **miniz** can be used internally)
|
||||
* **MO3** support requires:
|
||||
* **libmpg123 >= 1.14.0** (or **minimp3 by Lion (github.com/lieff)** can
|
||||
be used internally)
|
||||
* **libogg**, **libvorbis**, and **libvorbisfile** (or **stb_vorbis** can
|
||||
be used internally)
|
||||
* Building on Unix-like systems requires:
|
||||
* **GNU make**
|
||||
* **pkg-config**
|
||||
* The Autotools-based build system requires:
|
||||
* **pkg-config 0.24** or higher
|
||||
* **zlib**
|
||||
* **doxygen**
|
||||
|
||||
### openmpt123
|
||||
|
||||
* Live sound output requires one of:
|
||||
* **PulseAudio**
|
||||
* **SDL 2**
|
||||
* **PortAudio v19**
|
||||
* **Win32**
|
||||
* **liballegro 4.2** on DJGPP/DOS
|
||||
|
||||
|
||||
Optional dependencies
|
||||
---------------------
|
||||
|
||||
### libopenmpt
|
||||
|
||||
* **doxygen 1.8** or higher is required to build the documentation.
|
||||
|
||||
### openmpt123
|
||||
|
||||
* Rendering to PCM files can use:
|
||||
* **FLAC 1.2** or higher
|
||||
* **libsndfile**
|
||||
* **Win32** for WAVE
|
||||
* raw PCM has no external dependencies
|
||||
* **help2man** is required to build the documentation.
|
||||
|
||||
|
||||
Source packages
|
||||
---------------
|
||||
|
||||
Building the source packages additionally requires:
|
||||
* 7z (7-zip)
|
||||
* autoconf
|
||||
* autoconf-archive
|
||||
* automake
|
||||
* awk (mawk)
|
||||
* git
|
||||
* gzip
|
||||
* help2man
|
||||
* libtool
|
||||
* subversion
|
||||
* tar
|
||||
* xpath (libxml-xpath-perl)
|
||||
* zip
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
|
||||
Getting Started {#gettingstarted}
|
||||
===============
|
||||
|
||||
|
||||
How to compile
|
||||
--------------
|
||||
|
||||
|
||||
### libopenmpt and openmpt123
|
||||
|
||||
- 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 in the matching
|
||||
`build/vsVERSIONwinWINDOWSVERSION/` folder.
|
||||
Minimal projects that target Windows 10 UWP are available in
|
||||
`build/vsVERSIONuwp/`.
|
||||
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 amd64 or ARM64 when
|
||||
building with Visual Studio.
|
||||
|
||||
- In order to build libopenmpt for Windows XP, the Visual Studio 2017 XP
|
||||
targetting toolset as well as the Windows 8.1 SDK need to be installed.
|
||||
The SDK is optionally included with Visual Studio 2017, but must be
|
||||
separately installed with later Visual Studio versions.
|
||||
|
||||
The Windows 8.1 SDK is available from
|
||||
<https://developer.microsoft.com/en-us/windows/downloads/sdk-archive/>
|
||||
or directly from
|
||||
<https://download.microsoft.com/download/B/0/C/B0C80BA3-8AD6-4958-810B-6882485230B5/standalonesdk/sdksetup.exe>
|
||||
.
|
||||
|
||||
- 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.
|
||||
|
||||
- native build:
|
||||
|
||||
Simply run
|
||||
|
||||
make
|
||||
|
||||
which will try to guess the compiler based on your operating system.
|
||||
|
||||
- gcc or clang (on Unix-like systems, including Mac OS X with MacPorts,
|
||||
and Haiku (32-bit Hybrid and 64-bit)):
|
||||
|
||||
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 you want to use gcc, run:
|
||||
|
||||
make CONFIG=gcc
|
||||
|
||||
When you want to use clang, it is recommended to do:
|
||||
|
||||
make CONFIG=clang
|
||||
|
||||
- mingw-w64:
|
||||
|
||||
make CONFIG=mingw64-win32 # for win32
|
||||
|
||||
make CONFIG=mingw64-win64 # for win64
|
||||
|
||||
- emscripten (on Unix-like systems):
|
||||
|
||||
Run:
|
||||
|
||||
# generates WebAssembly with JavaScript fallback
|
||||
make CONFIG=emscripten EMSCRIPTEN_TARGET=all
|
||||
|
||||
or
|
||||
|
||||
# generates WebAssembly
|
||||
make CONFIG=emscripten EMSCRIPTEN_TARGET=wasm
|
||||
|
||||
or
|
||||
|
||||
# generates JavaScript 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. 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 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 source
|
||||
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 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`.
|
||||
|
|
@ -0,0 +1,43 @@
|
|||
|
||||
/*!
|
||||
* \mainpage Contents
|
||||
*
|
||||
* libopenmpt is a cross-platform C++ and C library to decode <a href="https://en.wikipedia.org/wiki/Module_file">tracked music files (modules)</a> into a raw PCM audio stream.
|
||||
*
|
||||
* libopenmpt is based on the player code of the Open ModPlug Tracker project (OpenMPT, <a href="https://openmpt.org/">https://openmpt.org/</a>)
|
||||
*
|
||||
* \section toc Contents
|
||||
* - \ref md_README "README"
|
||||
* - \ref dependencies "Dependencies"
|
||||
* - \ref gettingstarted "Getting Started"
|
||||
* - \ref packaging "Packaging"
|
||||
* - \ref md_doc_contributing "Contributing"
|
||||
* - \ref md_doc_libopenmpt_styleguide "libopenmpt Style Guide"
|
||||
* - \ref md_doc_openmpt_styleguide "OpenMPT Style Guide"
|
||||
* - \ref tests "Tests"
|
||||
* - \ref changelog "Changelog"
|
||||
* - \ref md_doc_module_formats "Implementing new Module Formats"
|
||||
* - <a href="https://bugs.openmpt.org/">Issue Tracker</a>
|
||||
* \subsection toc_apis APIs
|
||||
* - libopenmpt
|
||||
* - \ref libopenmpt "Common Details"
|
||||
* - libopenmpt C++
|
||||
* - \ref libopenmpt_cpp_overview "Overview"
|
||||
* - \ref libopenmpt_cpp "Details"
|
||||
* - libopenmpt C
|
||||
* - \ref libopenmpt_c_overview "Overview"
|
||||
* - \ref libopenmpt_c "Details"
|
||||
* - libopenmpt_ext C++
|
||||
* - \ref libopenmpt_ext_cpp_overview "Overview"
|
||||
* - \ref libopenmpt_ext_cpp "Details"
|
||||
* - libopenmpt_ext C
|
||||
* - \ref libopenmpt_ext_c_overview "Overview"
|
||||
* - \ref libopenmpt_ext_c "Details"
|
||||
*
|
||||
* \section toc_website Website
|
||||
* https://lib.openmpt.org/
|
||||
*
|
||||
* \section toc_license License
|
||||
* \include LICENSE
|
||||
*
|
||||
*/
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
Packaging {#packaging}
|
||||
=========
|
||||
|
||||
|
||||
Packaging
|
||||
---------
|
||||
|
||||
|
||||
### Packaging recommendations for distribution package maintainers
|
||||
|
||||
* libopenmpt (since 0.3) uses SemVer 2.0.0 versioning. See
|
||||
[semver.org](https://semver.org/spec/v2.0.0.html). Clause 4 is ignored for
|
||||
libopenmpt, which means that libopenmpt will also provide API/ABI
|
||||
compatibility semantics for pre-1.0.0 versions as required by SemVer 2.0.0
|
||||
only for post-1.0.0 versions. The SemVer versioning scheme is incompatible
|
||||
with Debian/Ubuntu package versions, however it can easily be processed to
|
||||
be compatible by replacing '-' (hyphen) with '~' (tilde). It is recommended
|
||||
that you use this exact transformation if required.
|
||||
* Use the autotools source package.
|
||||
* Use the default set of dependencies required by the autotools package.
|
||||
* Read \ref libopenmpt_c_staticlinking and thus possibly pass
|
||||
`CXXSTDLIB_PCLIBSPRIVATE` variable to `configure` if appropriate and/or
|
||||
desired.
|
||||
* Run the test suite in your build process.
|
||||
* Send any build system improvement patches upstream.
|
||||
* Do not include the libmodplug emulation layer in the default libopenmpt
|
||||
binary package. Either do not package it at all, or provide a separate
|
||||
package named libopenmpt-modplug or libmodplug-openmpt (or similar), which
|
||||
depends on libopenmpt, provides libmodplug, and conflicts with original
|
||||
libmodplug.
|
||||
* Split openmpt123 into its own binary package because it has more
|
||||
dependencies than libopenmpt itself.
|
||||
* Consider providing an additional openmpt123 package (in addition to the
|
||||
default openmpt123 package with all audio output drivers), built with fewer
|
||||
audio output drivers so it does not transitively depend on X11. Name that
|
||||
package and its executable openmpt123-nox (or whatever else may be common
|
||||
practice in your distribution).
|
||||
|
||||
|
|
@ -0,0 +1,44 @@
|
|||
|
||||
Tests {#tests}
|
||||
=====
|
||||
|
||||
|
||||
libopenmpt provides some basic unit tests that check the platform for general
|
||||
sanity and do some basic internal functionality testing. The test suite
|
||||
requires a special libopenmpt build that includes file saving functionality
|
||||
which is not included in normal builds. This is handled by all provided build
|
||||
systems automatically.
|
||||
|
||||
### Running Tests
|
||||
|
||||
#### On Unix-like systems
|
||||
|
||||
Compile with
|
||||
|
||||
make $YOURMAKEOPTIONS clean
|
||||
make $YOURMAKEOPTIONS
|
||||
|
||||
and run
|
||||
|
||||
make $YOURMAKEOPTIONS check
|
||||
|
||||
As the build system retains no state between make invocations, you have to
|
||||
provide your make options on every make invocation.
|
||||
|
||||
#### Autotools-based build system
|
||||
|
||||
./configure
|
||||
make check
|
||||
|
||||
#### On Windows
|
||||
|
||||
Using Visual Studio 20??, compile
|
||||
|
||||
build\vs20??\libopenmpt_test.sln
|
||||
|
||||
and run
|
||||
|
||||
bin\$ARCH\libopenmpt_test.exe
|
||||
|
||||
from the root of the source tree.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue