Initial community commit

Src/external_dependencies/openmpt-trunk/doc/backporting_patches.md

@@ -0,0 +1,37 @@
+
+Backporting patches
+===================
+
+This document tries to list all changes that must be made to individual
+patches when backporting them to earlier branches of the codebase.
+
+This list is incomplete.
+
+OpenMPT 1.28 / libopenmpt 0.4
+-----------------------------
+
+ *  Replace `std::abs` by `mpt::abs`.
+ *  Replace `std::byte` by `mpt::byte`.
+ *  Replace `std::clamp` by `mpt::clamp`.
+ *  Replace `std::data` by `mpt::data`.
+ *  Replace `std::gcd` by `mpt::gcd`.
+ *  Replace `std::lcm` by `mpt::lcm`.
+ *  Replace `std::make_unique` by `mpt::make_unique`.
+ *  Replace `std::size` by `mpt::size`.
+ *  Replace `if constexpr` by `MPT_CONSTANT_IF`.
+ *  Replace `static_assert` by `MPT_STATIC_ASSERT`.
+ *  Replace `[[nodiscard]]` by `MPT_NODISCARD`.
+ *  Replace `[[fallthrough]]` by `MPT_FALLTHROUGH`.
+ *  Reokace `mpt::lock_guard` by `MPT_LOCK_GUARD`.
+
+OpenMPT 1.27 / libopenmpt 0.3 
+-----------------------------
+
+ *  Replace string macros with longer versions:
+     *  U_("foo") --> MPT_USTRING("foo")
+     *  UL_("foo") --> MPT_ULITERAL("foo")
+     *  UC_('x') --> MPT_UCHAR('x')
+     *  P_("foo") --> MPT_PATHSTRING("foo")
+     *  PL_("foo") --> MPT_PATHSTRING_LITERAL("foo")
+     *  PC_('x') --> MPT_PATHSTRING_LITERAL('x')
+    See <https://bugs.openmpt.org/view.php?id=1107>.

Src/external_dependencies/openmpt-trunk/doc/contributing.md

@@ -0,0 +1,43 @@
+
+Contributing
+============
+
+OpenMPT, libopenmpt, openmpt123, xmp-openmpt and in_openmpt are developed in
+the Subversion repository at
+[https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/](https://source.openmpt.org/browse/openmpt/trunk/OpenMPT/).
+Patches can be provided either against this Subversion repository or against our
+GitHub mirror at
+[https://github.com/OpenMPT/openmpt/](https://github.com/OpenMPT/openmpt/).
+
+We do not have a developer mailing list. Discussions about new features or
+problems can happen at:
+ *  [Issue Tracker](https://bugs.openmpt.org/), preferred for specific bug
+    reports or bug fixes and feature development discussion
+ *  [Forum](https://forum.openmpt.org/), preferred for long-term discussion of
+    new features or specific questions about development
+ *  [IRC channel (`EsperNET/#modplug`)](irc://irc.esper.net:5555/#modplug),
+    preferred for shorter questions
+ *  [GitHub pull requests](https://github.com/OpenMPT/openmpt/pulls), please
+    only use for rather tiny fixes, see below
+
+For patch submissions, please also see
+[OpenMPT style guide](openmpt_styleguide.md) and
+[libopenmpt style guide](libopenmpt_styleguide.md).
+
+### Contributing via GitHub
+
+As OpenMPT is developed in a Subversion repository and the GitHub repository is
+just mirrored from that, we cannot directly take pull requests via GitHub. We
+recognize that, especially for tiny bug fixes, the burden to choose a different
+way than GitHub for contributing can be too high. Thus, we will of course react,
+give feedback, and take patches also via GitHub pull requests. However, as the
+GitHub repository is strictly downstream from our Subversion repository (and
+this will not change, due to considerable complications when synchronizing this
+two-way), we cannot directly merge pull requests on GitHub. We will merge
+contributions to our Subversion repository, which will then in turn be mirrored
+to GitHub automatically, after which we will close the pull request. Authorship
+attribution in git relies on the email address used in the commit header, which
+is not how it usually works in Subversion. We will thus add an additional line
+to the commit message in the form of `Patch-by: John Doe <user@example.com>`. If
+you prefer to be attributed with your nickname and/or without your email
+address, that would also be fine for us.

Src/external_dependencies/openmpt-trunk/doc/libopenmpt_release.md

@@ -0,0 +1,49 @@
+libopenmpt release process
+==========================
+
+0.3
+---
+
+For libopenmpt 0.3, see
+https://source.openmpt.org/svn/openmpt/branches/OpenMPT-1.27/doc/libopenmpt_release.txt
+.
+
+0.4
+---
+
+For libopenmpt 0.4, see
+https://source.openmpt.org/svn/openmpt/branches/OpenMPT-1.28/doc/libopenmpt_release.txt
+.
+
+0.5
+---
+
+For libopenmpt 0.4, see
+https://source.openmpt.org/svn/openmpt/branches/OpenMPT-1.29/doc/libopenmpt_release.txt
+.
+
+0.6
+---
+
+ 1. ensure that the OpenMPT version is preferrably at a aa.bb.cc.00 version,
+    otherwise increment the minorminor part to a new value used specifically for
+    the libopenmpt release
+ 2. from a clean checkout, run (requires xpath!!!)
+        ./build/svn/do_libopenmpt_release.sh
+ 3. website: add release announcement
+ 4. website: update download links
+ 5. wait for buildbot
+ 6. in a website checkout, run (as printed by the release script)
+        ./release-0.5.sh $NEWVER +release
+ 7. increment OpenMPT version minorminor in `common/versionNumber.h` when all
+    releases are done on the svn side (either libopenmpt only, or both
+    libopenmpt and OpenMPT)
+
+release candidate
+-----------------
+
+ 1. `./build/update_libopenmpt_version.sh release-rc 1`
+ 2. `svn commit -m '[Mod] libopenmpt: Bump rc version.'`
+ 3. `./build/svn/do_libopenmpt_release_rc.sh`
+ 4. `./build/update_libopenmpt_version.sh release-rc 2`
+ 5. `svn commit -m '[Mod] libopenmpt: Bump rc version.'`

Src/external_dependencies/openmpt-trunk/doc/libopenmpt_styleguide.md

@@ -0,0 +1,104 @@
+
+libopenmpt Style Guide
+======================
+
+
+### libopenmpt
+
+**Note:**
+**This applies to `libopenmpt/` and `openmpt123/` directories only.**
+**Use OpenMPT style otherwise.**
+
+The code generally tries to follow these conventions, but they are not
+strictly enforced and there are valid reasons to diverge from these
+conventions. Using common sense is recommended.
+
+ -  In general, the most important thing is to keep style consistent with
+    directly surrounding code.
+ -  Use C++ std types when possible, prefer `std::size_t` and `std::int32_t`
+    over `long` or `int`. Do not use C99 std types (e.g. no pure `int32_t`)
+ -  Qualify namespaces explicitly, do not use `using`.
+    Members of `namespace openmpt` can be named without full namespace
+    qualification.
+ -  Prefer the C++ version in `namespace std` if the same functionality is
+    provided by the C standard library as well. Also, include the C++
+    version of C standard library headers (e.g. use `<cstdio>` instead of
+    `<stdio.h>`.
+ -  Do not use ANY locale-dependant C functions. For locale-dependant C++
+    functionaly (especially iostream), always imbue the
+    `std::locale::classic()` locale.
+ -  Prefer kernel_style_names over CamelCaseNames.
+ -  If a folder (or one of its parent folders) contains .clang-format,
+    use clang-format v3.5 for indenting C++ and C files, otherwise:
+     -  `{` are placed at the end of the opening line.
+     -  Enclose even single statements in curly braces.
+     -  Avoid placing single statements on the same line as the `if`.
+     -  Opening parentheses are separated from keywords with a space.
+     -  Opening parentheses are not separated from function names.
+     -  Place spaces around operators and inside parentheses.
+     -  Align `:` and `,` when inheriting or initializing members in a
+        constructor.
+     -  The pointer `*` is separated from both the type and the variable name.
+     -  Use tabs for identation, spaces for formatting.
+        Tabs should only appear at the very beginning of a line.
+        Do not assume any particular width of the TAB character. If width is
+        important for formatting reasons, use spaces.
+     -  Use empty lines at will.
+ -  API documentation is done with doxygen.
+    Use general C doxygen for the C API.
+    Use QT-style doxygen for the C++ API.
+
+#### libopenmpt indentation example
+
+~~~~{.cpp}
+namespace openmpt {
+
+// This is totally meaningless code and just illustrates indentation.
+
+class foo
+	: public base
+	, public otherbase
+{
+
+private:
+
+	std::int32_t x;
+	std::int16_t y;
+
+public:
+
+	foo()
+		: x(0)
+		, y(-1)
+	{
+		return;
+	}
+
+	int bar() const;
+
+}; // class foo
+
+int foo::bar() const {
+
+	for ( int i = 0; i < 23; ++i ) {
+		switch ( x ) {
+			case 2:
+				something( y );
+				break;
+			default:
+				something( ( y - 1 ) * 2 );
+				break;
+		}
+	}
+	if ( x == 12 ) {
+		return -1;
+	} else if ( x == 42 ) {
+		return 1;
+	}
+	return 42;
+
+}
+
+} // namespace openmpt
+~~~~
+

Src/external_dependencies/openmpt-trunk/doc/module_formats.md

@@ -0,0 +1,107 @@
+Adding support for new module formats
+=====================================
+
+This document describes the basics of writing a new module loader and related
+work that has to be done. We will not discuss in detail how to write the loader,
+have a look at existing loaders to get an idea how they work in general.
+
+General hints
+-------------
+* We strive for quality over quantity. The goal is not to support as many module
+  formats as possible, but to support them as well as possible. 
+* Write defensive code. Guard against out-of-bound values, division by zero and
+  similar stuff. libopenmpt is constantly fuzz-tested to catch any crashes, but
+  of course we want our code to be reliable from the start.
+* Every format should have its own `MODTYPE` flag, unless it can be reasonably
+  represented as a subset of another format (like Ice Tracker ICE files being
+  a subset of ProTracker MOD).
+* When reading binary structs from the file, use our data types with defined
+  endianness, which can be found in `common/Endianness.h`:
+  * Big-Endian: (u)int8/16/32/64be, float32be, float64be
+  * Little-Endian: (u)int8/16/32/64le, float32le, float64le
+
+  Entire structs containing integers with defined endianness can be read in one
+  go if they are tagged with `MPT_BINARY_STRUCT` (see existing loaders for an
+  example).
+* `CSoundFile::m_nChannels` **MUST NOT** be changed after a pattern has been
+  created, as existing patterns will be interpreted incorrectly. For module
+  formats that support per-pattern channel amounts, the maximum number of
+  channels must be determined beforehand.
+* Strings can be safely handled using:
+  * `FileReader::ReadString` and friends for reading them directly from a file
+  * `mpt::String::ReadBuf` for reading them from a struct or char array
+
+  These functions take care of string padding (zero / space padding) and will
+  avoid reading past the end of the string if there is no terminating null
+  character.
+* Do not use non-const static variables in your loader. Loaders need to be
+  thread-safe for libopenmpt.
+* `FileReader` instances may be used to treat a portion of a file as its own
+  independent file (through `FileReader::ReadChunk`). This can be useful with
+  "embedded files" such as WAV or Ogg samples. Container formats such as UMX
+  are another good example for this usage.
+* Samples *either* use middle-C frequency *or* finetune + transpose. For the few
+  weird formats that use both, it may make sense to translate everything into
+  middle-C frequency.
+* Add the new `MODTYPE` to `CSoundFile::UseFinetuneAndTranspose` if applicable,
+  and see if any effect handlers in `soundlib/Snd_fx.cpp` need to know the new
+  `MODTYPE`.
+* Do not rely on hard-coded magic numbers. For example, when comparing if an
+  index is valid for a given array, do not hard-code the array size but rather
+  use `std::size` (or `mpt::array_size` in contexts where `std::size` is not
+  usable) or, for ensuring that char arrays are null-terminated,
+  `mpt::String::SetNullTerminator`. Similarly, do not assume any specific
+  quantities for OpenMPT's constants like MAX_SAMPLES, MAX_PATTERN_ROWS, etc.
+  These may change at any time.
+* Pay attention to off-by-one errors when comparing against MAX_SAMPLES and
+  MAX_INSTRUMENTS, since sample and instrument numbers are 1-based. Prefer using
+  `CSoundFile::CanAddMoreSamples` and `CSoundFile::CanAddMoreInstruments` to
+  check if a given amount of samples or instruments can be added to the file
+  rather than doing the calculations yourself.
+* Placement of the loader function in the `ModuleFormatLoaders` array in
+  Sndfile.cpp depends on various factors. In general, module formats that have
+  very bad magic numbers (and thus might cause other formats to get
+  mis-interpreted) should be placed at the bottom of the list. Two notable
+  examples are 669 files, where the first two bytes of the file are "if"
+  (which may e.g. cause a song title starting with if ..." in various other
+  formats to be interpreted as a 669 module), and of course
+  Ultimate SoundTracker modules, which have no magic bytes at all.
+* Avoid use of functions tagged with [[deprecated]].
+
+Probing
+-------
+libopenmpt provides fast probing functions that can be used by library users
+to quickly check if a file is most likely playable with libopenmpt, even if only
+a fraction of the file is available (e.g. when streaming from the internet).
+
+In order to satisfy these requirements, probing functions should do as little
+work as possible (e.g. only parse the header of the file), but as much as
+required to tell with some certainty that the file is really of a certain mod
+format. However, probing functions should not rely on having access to more than
+the first `CSoundFile::ProbeRecommendedSize` bytes of the file.
+
+* Probing functions **must not** allocate any memory on the heap.
+* Probing functions **must not** return ProbeFailure or ProbeWantMoreData for
+  any file that would normally be accepted by the loader. In particular, this
+  means that any header checks must not be any more aggressive than they would
+  be in the real loader (hence it is a good idea to not copy-paste this code but
+  rather put it in a separate function), and the minimum additional size passed
+  to `CSoundFile::ProbeAdditionalSize` must not be higher than the biggest size
+  that would cause a hard failure (i.e. returning `false`) in the module loader.
+* Probing functions **may** return ProbeSuccess for files that would be rejected
+  by a loader after a more thorough inspection. For example, probing functions
+  do not need to verify that all required chunks of an IFF-like file format are
+  actually present, if the header makes it obvious enough that the file is
+  highly likely to be a module.
+
+Adding loader to the build systems and various other locations
+--------------------------------------------------------------
+Apart from writing the module loader itself, there are a couple of other places
+that need to be updated:
+* Add loader file to `build/android_ndk/Android.mk`.
+* Add loader file to `build/autotools/Makefile.am`.
+* Run `build/regenerate_vs_projects.sh` / `build/regenerate_vs_projects.cmd`
+  (depending on your platform)
+* Add file extension to `installer/filetypes-*.iss`.
+* Add file extension to `CTrackApp::OpenModulesDialog` in `mptrack/Mptrack.cpp`.
+* Add format information to `soundlib/Tables.cpp`.

Src/external_dependencies/openmpt-trunk/doc/openmpt_release.md

@@ -0,0 +1,67 @@
+OpenMPT release process
+=======================
+
+0. A day or so before the release, restart all fuzzers with the latest binaries
+   and check if any unexpected crashes occur. Module loaders should not be
+   touched in this phase to prevent the introduction of unexpected crashes.
+1. Update `Release Notes.html`, `History.txt`, `readme.txt` and
+   `versionNumber.h`
+   * Update version number in all files
+   * If year changed, see `doc/year_changed.md`
+2. Download latest pinned externals via build/download_externals.cmd.
+3. Run `build/auto/build_openmpt_release_manual.cmd` to build OpenMPT and the
+   release packages.
+4. Upload release packages (openmpt.org, ftp.untergrund.net, SourceForge)
+5. Upload `OMPT_X.YY_ReleaseNotes.html` and `History.txt` to
+   https://openmpt.org/release_notes/ (update DirectoryIndex on major version change!)
+6. Update https://openmpt.org/download
+7. Write news entry for front page
+8. Update stable.php version information and api/v3/update/release for update checker
+9. Create SVN tag
+10. Update forum pre-announcement post, if there was one
+11. Update release status on issue tracker, add new test version and upcoming
+    stable version.
+12. Update IRC topic
+13. Write BitFellas news article
+14. Clear https://wiki.openmpt.org/Special:WhatLinksHere/Template:NewVersion
+15. Backup PDB files
+
+Order of sections in History.txt
+--------------------------------
+ *  General tab
+ *  Pattern tab
+ *  Pattern Tab::Note Properties
+ *  Pattern tab::Find/Replace
+ *  Sample tab
+ *  Instrument tab
+ *  Comments tab
+ *  Tree view
+ *  Mod Conversion
+ *  MIDI Macros
+ *  VST / DMO Plugins
+ *  VST::Specific Plugin Fixes
+ *  VST::Plugin Bridge
+ *  Playback
+ *  MPTM
+ *  MPTM::Custom Tuning
+ *  IT / MPTM
+ *  IT
+ *  IT:Loading (and Saving)
+ *  IT::Compatible Playback Mode
+ *  XM
+ *  XM::Loading (and Saving)
+ *  XM::Compatible Playback Mode
+ *  S3M
+ *  S3M:Loading (and Saving)
+ *  MOD
+ *  MOD::ProTracker 1/2 Mode
+ *  MOD::Loading (and Saving)
+ *  Other formats
+ *  Stream Export
+ *  Module cleanup
+ *  Audio I/O
+ *  Misc
+ *  Bundled plugins
+ *  Third-Party Libraries
+ *  Installer/release package
+

Src/external_dependencies/openmpt-trunk/doc/openmpt_styleguide.md

@@ -0,0 +1,35 @@
+
+OpenMPT Style Guide
+===================
+
+
+### OpenMPT
+
+**Note:**
+**This applies to all source code *except* for `libopenmpt/` and `openmpt123/`**
+**directories.**
+**Use libopenmpt style otherwise.**
+
+(see below for an example)
+
+ *  Place curly braces at the beginning of the line, not at the end
+ *  Generally make use of the custom index types like `SAMPLEINDEX` or
+    `ORDERINDEX` when referring to samples, orders, etc.
+ *  When changing playback behaviour, make sure that you use the function
+    `CSoundFile::IsCompatibleMode()` so that modules made with previous versions
+    of MPT still sound correct (if the change is extremely small, this might be
+    unnecessary)
+ *  `CamelCase` function and variable names are preferred.
+
+#### OpenMPT code example
+
+~~~~{.cpp}
+void Foo::Bar(int foobar)
+{
+    while(true)
+    {
+        // some code
+    }
+}
+~~~~
+

Src/external_dependencies/openmpt-trunk/doc/release_branches.md

@@ -0,0 +1,30 @@
+branching release branches
+==========================
+
+ 1. adjust buildbot configuration by copying current trunk configuration to a
+    new branch configuration and replace `trunk` with the branch version (i.e.
+    `127`), remember to also adjust url of nondist externals
+ 2. add release build configuration to the buildbot branch configuration file,
+    adjust buildbot config of release build configurations to output to the
+    separate auto-release directory and change the archive format from 7z to zip
+    for windows binaries
+ 3. branch the nondist externals repository
+ 4. branch the current trunk HEAD (`$VER` is the branch version):
+    `svn copy -m "branch OpenMPT-$VER" https://source.openmpt.org/svn/openmpt/trunk/OpenMPT https://source.openmpt.org/svn/openmpt/branches/OpenMPT-$VER`
+ 5. update versions in trunk
+    `https://source.openmpt.org/svn/openmpt/trunk/OpenMPT`:
+     1. set OpenMPT version in `common/versionNumber.h` to
+        `1.$(($VER + 1)).00.01`
+     2. run `build/update_libopenmpt_version.sh bumpminor`
+     3. run `build/update_libopenmpt_version.sh bumpltabi`
+     4. update version numbers in `build/svn/do_libopenmpt_release.sh` and
+        `build/svn/do_libopenmpt_release_rc.sh`
+ 6. update versions in branch
+    `https://source.openmpt.org/svn/openmpt/branches/OpenMPT-$VER`:
+     1. set OpenMPT version in `common/versionNumber.h` to
+        `1.$VER.00.$MINORMINOR+1`
+     2. run `build/update_libopenmpt_version.sh bumpprerel`
+ 7. add versioned libopenmpt release script for new branch which copies release
+    packages into place
+ 8. update buildbot scripts that copy OpenMPT update information into place
+ 9. update branch release date on libopenmpt trunk changelog

Src/external_dependencies/openmpt-trunk/doc/signing_releases.md

@@ -0,0 +1,43 @@
+
+building signed updates
+=======================
+
+ *  run
+    ```
+    build\download_externals.cmd
+    build\auto\build_openmpt_args.cmd vs2019 win10 Win32 Release 7z default
+    build\auto\build_openmpt_args.cmd vs2019 win10 x64   Release 7z default
+    build\auto\build_openmpt_args.cmd vs2019 win10 ARM   Release 7z default
+    build\auto\build_openmpt_args.cmd vs2019 win10 ARM64 Release 7z default
+    build\auto\build_openmpt_args.cmd vs2019 win7  Win32 Release 7z default
+    build\auto\build_openmpt_args.cmd vs2019 win7  x64   Release 7z default
+    build\auto\build_openmpt_release_packages_multiarch.cmd
+    build\auto\build_openmpt_update_information.cmd
+    build\auto\package_openmpt_installer_multiarch_args.cmd vs2019 win10 Win32 Release 7z default
+    ```
+    or just `build\auto\build_openmpt_release_manual.cmd`, which does all of the
+    above in one go.
+
+ *  results are found in `bin\openmpt-pkg.win-multi.tar`
+
+ *  `openmpt/pkg.win/${BRANCHVERSION}/OpenMPT-${VERSION}-update.json` contains
+    the update information that needs to be copied verbatim to the respective
+    update channel on update.openmpt.org. This file is not signed as it itself
+    is considered only informational and may be augmented with additional
+    information. The files it links that contain actual code and automated
+    update instructions are all signed.
+
+ *  If the current user did not yet have a signing key on the local computer, a
+    new key will be automatically generated and stored for future re-use in the
+    encrypted Windows Key Store. The public key to verify the signatures is
+    exported on each packaging of builds alongside the other build artefacts at
+    `openmpt/pkg.win/${BRANCHVERSION}/OpenMPT-${VERSION}-update-publickey.jwk.json`
+	. Any such new key should be added to the set of allowed update signing keys
+    in the repository at `build/signingkeys/`, as an individual file named
+    appropriately to describe the key (in order to easier identify the
+    individual keys), and as a key in the jwkset of allowed keys in the file
+    `build/signingkeys/signingkeys.jwkset.json`. A jwkset file consists of a
+    JSON object containing a single array of all individual keys, named `"keys"`
+    . The updated `signingkeys.jwkset.json` then needs to be copied to the https
+    locations where the update check checks for the anchor keys. There is no
+    separate key handling for test and release builds.

Src/external_dependencies/openmpt-trunk/doc/year_changed.md

@@ -0,0 +1,19 @@
+
+Things to update when the year has changed
+==========================================
+
+ *  `LICENSE` (1 occurrence)
+ *  `src/mpt/LICENSE.BSD-3-Clause.txt` (1 occurrence)
+ *  `common/version.cpp` (2 occurrences plus 1 for each current contributor)
+ *  `mptrack/res/MPTRACK.RC2` (1 occurence)
+ *  `pluginBridge/PluginBridge.rc` (1 occurence)
+ *  `installer/install-multi-arch.iss` (1 occurence)
+ *  `libopenmpt/libopenmpt_version.rc`) (1 occurrence)
+ *  `openmpt123/openmpt123.cpp` (3 occurrences)
+ *  `libopenmpt/xmp-openmpt.cpp` (1 occurrence)
+ *  `libopenmpt/in_openmpt.cpp` (1 occurrence)
+ *  `contrib/libmodplug-0.8.8.5/LICENSE` (1 occurrence)
+ *  `contrib/libmodplug-0.8.9.0/LICENSE` (1 occurrence)
+ *  [https://wiki.openmpt.org/Manual:_Acknowledgments](https://wiki.openmpt.org/Manual:_Acknowledgments)
+ *  [https://lib.openmpt.org/libopenmpt/license/](https://lib.openmpt.org/libopenmpt/license/)
+