diff options
Diffstat (limited to 'Src/external_dependencies/openmpt-trunk/doc')
10 files changed, 534 insertions, 0 deletions
diff --git a/Src/external_dependencies/openmpt-trunk/doc/backporting_patches.md b/Src/external_dependencies/openmpt-trunk/doc/backporting_patches.md new file mode 100644 index 00000000..d66aaf1d --- /dev/null +++ b/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>. diff --git a/Src/external_dependencies/openmpt-trunk/doc/contributing.md b/Src/external_dependencies/openmpt-trunk/doc/contributing.md new file mode 100644 index 00000000..e3eaa733 --- /dev/null +++ b/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. diff --git a/Src/external_dependencies/openmpt-trunk/doc/libopenmpt_release.md b/Src/external_dependencies/openmpt-trunk/doc/libopenmpt_release.md new file mode 100644 index 00000000..c0d60f40 --- /dev/null +++ b/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.'` diff --git a/Src/external_dependencies/openmpt-trunk/doc/libopenmpt_styleguide.md b/Src/external_dependencies/openmpt-trunk/doc/libopenmpt_styleguide.md new file mode 100644 index 00000000..a616395a --- /dev/null +++ b/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 +~~~~ + diff --git a/Src/external_dependencies/openmpt-trunk/doc/module_formats.md b/Src/external_dependencies/openmpt-trunk/doc/module_formats.md new file mode 100644 index 00000000..8cbd5773 --- /dev/null +++ b/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`. diff --git a/Src/external_dependencies/openmpt-trunk/doc/openmpt_release.md b/Src/external_dependencies/openmpt-trunk/doc/openmpt_release.md new file mode 100644 index 00000000..97660590 --- /dev/null +++ b/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 + diff --git a/Src/external_dependencies/openmpt-trunk/doc/openmpt_styleguide.md b/Src/external_dependencies/openmpt-trunk/doc/openmpt_styleguide.md new file mode 100644 index 00000000..0109819d --- /dev/null +++ b/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 + } +} +~~~~ + diff --git a/Src/external_dependencies/openmpt-trunk/doc/release_branches.md b/Src/external_dependencies/openmpt-trunk/doc/release_branches.md new file mode 100644 index 00000000..ba59bd53 --- /dev/null +++ b/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 diff --git a/Src/external_dependencies/openmpt-trunk/doc/signing_releases.md b/Src/external_dependencies/openmpt-trunk/doc/signing_releases.md new file mode 100644 index 00000000..43d2aec1 --- /dev/null +++ b/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. diff --git a/Src/external_dependencies/openmpt-trunk/doc/year_changed.md b/Src/external_dependencies/openmpt-trunk/doc/year_changed.md new file mode 100644 index 00000000..6563f4cf --- /dev/null +++ b/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/) + |