Fix OpenDingux/build.sh buildroot prep

1. Creates the missing `shared-dl` directory.
2. Unsets some environment variables that interfere with buildroot.
3. Disables `BR2_PER_PACKAGE_DIRECTORIES`, which prevented us
   from using the partial sysroot build.

Also documents the `TOOLCHAIN=...` option in docs/building.md.

Packaging/OpenDingux/README.md

@@ -1,3 +1,3 @@
 # DevilutionX OpenDingux Port
 
-See README.md in the root directory for build instructions.
+See docs/building.md for build instructions.

Packaging/OpenDingux/build.sh

@@ -149,18 +149,40 @@ prepare_buildroot() {
 		git clone --depth=1 "${BUILDROOT_REPOS[$BUILDROOT_TARGET]}" "$BUILDROOT"
 	fi
 	cd "$BUILDROOT"
+	mkdir -p ../shared-dl
 	ln -s ../shared-dl dl
 
 	# Work around a BR2_EXTERNAL initialization bug in older buildroots.
 	mkdir -p output
 	touch output/.br-external.mk
-	make ${BUILDROOT_DEFCONFIGS[$BUILDROOT_TARGET]}
+	local -a config_args=(${BUILDROOT_DEFCONFIGS[$BUILDROOT_TARGET]})
+	local -r config="${config_args[0]}"
+
+	# If the buildroot uses per-package directories, disable them.
+	# Otherwise, we'd have to buildroot the entire buildroot (up to `host-finalize`) to get
+	# the merged host directory.
+	if grep -q BR2_PER_PACKAGE_DIRECTORIES=y "configs/${config}"; then
+		local -r new_config="${config%_defconfig}_no_ppd_defconfig"
+		sed 's/BR2_PER_PACKAGE_DIRECTORIES=y/# BR2_PER_PACKAGE_DIRECTORIES is not selected/' \
+		  "configs/${config}" > "configs/${new_config}"
+		config_args[0]="$new_config"
+	fi
+
+	make "${config_args[@]}"
 	cd -
 }
 
 make_buildroot() {
 	cd "$BUILDROOT"
-	BR2_JLEVEL=0 make toolchain sdl
+	local -a env_args=(
+	  # Unset client variables that cause issues with buildroot
+	  -u PERL_MM_OPT
+	  -u CMAKE_GENERATOR -u CMAKE_GENERATOR_PLATFORM -u CMAKE_GENERATOR_TOOLSET -u CMAKE_GENERATOR_INSTANCE
+
+	  # Enable parallelism
+	  BR2_JLEVEL=0
+	)
+	env "${env_args[@]}" make toolchain sdl
 	cd -
 }
 

docs/building.md

@@ -356,33 +356,38 @@ cmake --build build -j $(getconf _NPROCESSORS_ONLN)
 
 <details><summary>OpenDingux / RetroFW</summary>
 
-DevilutionX uses buildroot to build packages for OpenDingux and RetroFW.
+DevilutionX uses buildroot-based toolchains to build packages for OpenDingux and RetroFW.
 
-The build script does the following:
+For OpenDingux / RetroFW builds, `mksquashfs` needs to be installed on your machine.
 
-1. Downloads and configures the buildroot if necessary.
+To build, run the following command:
-2. Builds the executable (using CMake).
-3. Packages the executable and all related resources into an `.ipk` or `.opk` package.
 
-The buildroot uses ~2.5 GiB of disk space and can take 20 minutes to build.
+~~~ bash
+TOOLCHAIN=<path/to/toolchain> Packaging/OpenDingux/build.sh <platform>
+~~~
 
-For OpenDingux builds `mksquashfs` needs to be installed.
+Replace `<platform>` with one of: `lepus`, `retrofw`, `rg99`, `rg350`, or `gkd350h`.
 
-To build, run the following command
+For example:
 
 ~~~ bash
-Packaging/OpenDingux/build.sh <platform>
+TOOLCHAIN=/opt/gcw0-toolchain Packaging/OpenDingux/build.sh rg350
 ~~~
 
-Replace `<platform>` with one of: `retrofw`, `rg350`, or `gkd350h`.
+You can download the prebuilt toolchains for `x86_64` hosts here:
+
+* OpenDingux: https://github.com/OpenDingux/buildroot/releases
+* RetroFW: https://github.com/Poligraf/retrofw_buildroot_gcc11/releases
 
-This prepares and uses the buildroot at `$HOME/buildroot-$PLATFORM-devilutionx`.
+Remember to run `./relocate-sdk.sh` in the toolchain directory after unpacking it.
 
-End-user manuals are available here:
+Alternatively, if you do not set `TOOLCHAIN`, the script will
+download and compile a partial buildroot toolchain for you
+(stored at `$HOME/buildroot-$PLATFORM-devilutionx`).
+This requires 8 GiB+ disk space and takes a while.
 
-* [RetroFW manual](docs/manual/platforms/retrofw.md)
+End-user manuals are available [here](manual/platforms) and
-* [RG-350 manual](docs/manual/platforms/rg350.md)
+in the package help section.
-* [GKD350h manual](docs/manual/platforms/gkd350h.md)
 
 </details>