commit edd05644115f94cc939d869b09f30b92be7c1ddb
parent 14196de504e4dcacb9bebddf837a9aa25c687f8c
Author: Iván Ávalos <avalos@disroot.org>
Date: Tue, 17 Mar 2026 09:05:33 +0100
add README to subprojects/
Diffstat:
| A | subprojects/README.md | | | 95 | +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ |
1 file changed, 95 insertions(+), 0 deletions(-)
diff --git a/subprojects/README.md b/subprojects/README.md
@@ -0,0 +1,95 @@
+# Upgrading a subproject
+
+Some of the subprojects in this directory are using hand-written Meson
+build files, which must be kept in sync with the official ones. In
+order to upgrade a dependency, it is advisable to check for breaking
+changes in the API and build configuration, adjust the code
+accordingly, and then follow the instructions below:
+
+## Pre-upgrade
+
+### 1. Download and extract the latest tarball, e.g.
+
+```
+subprojects/
+├── libsodium/
+└── libsodium-stable/
+```
+
+## Upgrade
+
+### libsodium
+
+#### 1. Copy meson files to extracted tarball
+
+```
+$ find libsodium/ -name '*meson*'
+libsodium/src/libsodium/include/sodium/meson.build
+libsodium/meson.build
+libsodium/meson_options.txt
+```
+
+#### 2. Copy `checkprogs` subdirectory
+
+```
+cp -r libsodium/checkprogs/ libsodium-stable/
+```
+
+#### 2. Copy the files into the extracted tarball
+
+#### 3. Compare `src/libsodium/Makefile.am` and update source files
+
+Including the architecture specific ones!
+
+#### 4. Bump major and minor versions in main `meson.build`
+
+```meson
+conf_data = configuration_data()
+conf_data.set('VERSION', '1.0.20')
+conf_data.set('SODIUM_LIBRARY_VERSION_MAJOR', 26)
+conf_data.set('SODIUM_LIBRARY_VERSION_MINOR', 2)
+conf_data.set('SODIUM_LIBRARY_MINIMAL_DEF', '')
+subdir('src/libsodium/include/sodium')
+```
+
+They should match the ones in `src/Interop/Interop.Version.cs`.
+
+### curl
+
+#### 1. Copy meson files to extracted tarball
+
+```
+$ find curl/ -name '*meson*'
+libsodium/meson.build
+```
+
+#### 2. Compare `lib/Makefile.inc` and update source files in `meson.build`
+
+## Post-upgrade
+
+### 1. Swap the directories, e.g.
+
+```
+mv libsodium/ libsodium.old/
+mv libsodium-stable/ libsodium/
+```
+
+### 2. Test that compilation succeeds (and runs) for all platforms
+
+```
+# linux
+meson setup build
+meson compile -C build
+
+# android
+./cross/package-android.sh all
+
+# ios
+./cross/package-ios.sh
+```
+
+### 3. Delete the old version, e.g.
+
+```
+rm -rf libsodium.old/
+```
