meson: add temporary informative error

This adds an informative error to help users easily workaround the fact
that libopencm3 does not contain the meson overlay when fetched as a submodule
This should be temporary, and will be removed once libopencm3 upstream
contains a meson buildsystem

src/platforms/meson.build

@@ -39,7 +39,47 @@ Try adding the option `--cross-file @0@` for ARM based probes'''.format(
 )
 
 # include libopencm3 subproject, providing dependencies for some platforms
-libopencm3 = subproject('libopencm3')
+libopencm3 = subproject('libopencm3', required: false)
+if not libopencm3.found()
+	# Because for now we are sharing the directory for the libopencm3 subproject for meson and
+	# the libopencm3 submodule, and the upstream submodule does not contain the meson build
+	# we need to let meson fetch it itself as that is when the meson build overlay is applied,
+	# otherwise, meson detects that the subproject exists, but does not know what to do with it
+	# This is a workaround until the upstream buildsystem is updated to include the meson build
+	#
+	# This checks that the directory exists, and if it does, it checks if it contains the meson
+	# build overlay, if it does not, it means that the user cloned the submodule
+	#
+	# This just code is not required per-se, it is just here to provide the user with a better
+	# error message so they know what to do, as it is not obvious what and why the problem is
+	libopencm3_dir = meson.global_source_root() / 'deps' / 'libopencm3'
+	libopencm3_no_overlay = fs.is_dir(libopencm3_dir) and not fs.is_file(libopencm3_dir / 'meson.build')
+	error(
+		'libopencm3 subproject configuration failed',
+		libopencm3_no_overlay ? '''
+
+The subproject directory exists but does not contain the meson build overlay, this is likely
+because you cloned it as a submodule, either manually, or by running the `make` buildsystem
+
+Please remove the submodule and try again, you can do this by running the following commands on
+the root of the repository:
+ - `git submodule deinit --force deps/libopencm3`
+ - `meson subprojects purge --confirm libopencm3`
+
+Note that this will remove all files in `deps/libopencm3`, any changes you made will be lost.
+''' : '''
+
+An unknown problem ocurred, the subproject was not found but should have been fetched automatically
+
+Try the following:
+ - Make sure you have a working internet connection and try again
+ - Create a fresh build directory and configure without any extra options
+ - Make a fresh clone of the repository, do not clone the submodules, meson will take care of it
+
+If the problem persists, please report the issue to https://github.com/blackmagic-debug/blackmagic/issues
+''',
+	)
+endif
 
 subdir('common')
 subdir('stm32')