Add WITH_DEBUG option for building php-wasm with DWARF debug info (#47)

## Motivation for the change, related issues

Prior to this PR, we have built with DWARF debug info by manually
editing our php/Dockerfile, and it would be much better for devs to just
supply a command line option for creating such builds.

## Implementation details

This PR adds a `WITH_DEBUG` option that can be used like:
`npx nx recompile-php:asyncify php-wasm-web -- --PHP_VERSION=8.4
--WITH_DEBUG=yes`

It recompiles php-wasm to include DWARF debug info which may be used for
more detailed debugging in Chrome Canary. In contrast to debugging with
source maps, this way allows you to see more info like named variable
values in the step debugger. See
https://developer.chrome.com/docs/devtools/wasm for more info.

I considered merging the `WITH_SOURCEMAPS` option with this one, but in
my testing, it seemed like building with both DWARF info and sourcemaps
weakened the debug experience. For example, when building with just
DWARF debug info and debugging in Chrome canary, I noticed that I could
see the value of both `size` and `alignment` vars in the PHP memory
allocation code, but when building both debug info and sourcemaps, I
could only see the value of the `size` var. It's possible the difference
is a coincidence or due to some other issue, but I observed this
difference two or three times when testing different build types.

## Testing Instructions (or ideally a Blueprint)

- Install Chrome Canary if needed
- Add [the C/C++ Dev Tools Support
extension](https://chromewebstore.google.com/detail/cc++-devtools-support-dwa/pdcpmagijalfljmkmjngeonclgbbannb)
to Chrome Canary
- Run `npm run dev`
- Test building with source maps
- Run `npx nx recompile-php:asyncify php-wasm-web -- --PHP_VERSION=8.4
--WITH_SOURCEMAPS=yes`
- Make sure Playground web loads from the local server with PHP 8.4
selected
- Open dev tools to confirm you can open PHP source files like `main.c`
- Test building and using DWARF debug info
- Run `npx nx recompile-php:asyncify php-wasm-web -- --PHP_VERSION=8.4
--WITH_DEBUG=yes`
- Open the [debug extension
options](chrome-extension://pdcpmagijalfljmkmjngeonclgbbannb/ExtensionOptions.html)
- Add a path substitution to map `/root/php-src/` to the absolute path
the the php-src directory created by the php-wasm build.
- Note: Within your Playground repo, the relative path will be:
`packages/php-wasm/web/public/php/asyncify/8_4_0/php-src/`
- Make sure Playground web loads from the local server with PHP 8.4
selected.
  - Open dev tools.
- Reload Playground (reloading often seems to be needed to properly see
the C source files).
  - Open the PHP source file `zend_alloc.c`
- Locate the function `static void *zend_mm_chunk_alloc_int(size_t size,
size_t alignment)`
  - Set a breakpoint on the first line that permits breakpoints
  - Reload Playground and observe that you hit that breakpoint
- Confirm you can observe the function param values for `size` and
`alignment`
- Test normal php-wasm build
- Run `npx nx recompile-php:asyncify php-wasm-web -- --PHP_VERSION=8.4`
and confirm that Playground loads from the
local server with PHP 8.4 selected.

Author: brandonpayton

README.md

@@ -113,12 +113,18 @@ npx nx start php-wasm-cli
 # Build latest WordPress releases
 npx nx bundle-wordpress:all playground-wordpress-builds
 
-# Recompile PHP 7.0 - 8.3 releases to .wasm for web
+# Recompile PHP 7.0 - 8.4 releases to .wasm for web
 npx nx recompile-php:all php-wasm-web
 
-# Recompile PHP 7.0 - 8.3 releases to .wasm for node
+# Recompile PHP 7.0 - 8.4 releases to .wasm for node
 npx nx recompile-php:all php-wasm-node
 
+## Recompile with DWARF debug info for debugging
+npx nx recompile-php:all php-wasm-node --WITH_DEBUG=yes
+
+## Recompile with source maps for debugging
+npx nx recompile-php:all php-wasm-node --WITH_SOURCEMAPS=yes
+
 # Builds the documentation site
 npx nx build docs-site
 

packages/php-wasm/compile/build.js

@@ -91,6 +91,11 @@ const argParser = yargs(process.argv.slice(2))
 			choices: ['yes', 'no'],
 			description: 'Build with source maps',
 		},
+		WITH_DEBUG: {
+			type: 'string',
+			choices: ['yes', 'no'],
+			description: 'Build with DWARF debug information.',
+		},
 		WITH_ICONV: {
 			type: 'string',
 			choices: ['yes', 'no'],
@@ -220,6 +225,8 @@ await asyncSpawn(
 		'--build-arg',
 		`OUTPUT_DIR_FOR_SOURCE_MAP_BASE=${outputDir}`,
 		'--build-arg',
+		getArg('WITH_DEBUG'),
+		'--build-arg',
 		getArg('WITH_ICONV'),
 		'--build-arg',
 		getArg('WITH_MYSQL'),

packages/php-wasm/compile/php/Dockerfile

@@ -81,6 +81,7 @@ ARG WITH_OPENSSL
 ARG WITH_ICONV
 ARG WITH_SOURCEMAPS
 ARG OUTPUT_DIR_FOR_SOURCE_MAP_BASE
+ARG WITH_DEBUG
 ARG WITH_WS_NETWORKING_PROXY
 
 # The platform to build for: web or node
@@ -407,18 +408,22 @@ RUN if [[ "${PHP_VERSION:0:1}" -le "7" && "${PHP_VERSION:2:1}" -le "3" ]]; then
 
 ARG WITH_SOURCEMAPS
 ARG OUTPUT_DIR_FOR_SOURCE_MAP_BASE
+ARG WITH_DEBUG
 RUN set -euxo pipefail; \
 	if [ "$EMSCRIPTEN_ENVIRONMENT" = "node" ]; then \
 		# Add nodefs when building for node.js
 		echo -n ' -lnodefs.js ' >> /root/.emcc-php-wasm-flags; \
 	fi; \
-	if [ "${WITH_SOURCEMAPS}" = "yes" ]; then \
-		echo -n ' -g3 -gsource-map' >> /root/.emcc-php-wasm-flags; \
-		# Ensure source maps are loaded from the correct URL on the web.
-		# Without this, browsers will try the wasm:// protocol and never load the source map.
-		if [ "$EMSCRIPTEN_ENVIRONMENT" = "web" ]; then \
-			export PHP_VERSION_ESCAPED="${PHP_VERSION//./_}"; \
-			echo -n " --source-map-base http://127.0.0.1:5400/@fs${OUTPUT_DIR_FOR_SOURCE_MAP_BASE}/${PHP_VERSION_ESCAPED}/" >> /root/.emcc-php-wasm-flags; \
+	if [ "${WITH_SOURCEMAPS}" = "yes" ] || [ "${WITH_DEBUG}" = "yes" ]; then \
+		echo -n ' -g3 ' >> /root/.emcc-php-wasm-flags; \
+		if [ "${WITH_SOURCEMAPS}" = "yes" ]; then \
+			echo -n ' -gsource-map' >> /root/.emcc-php-wasm-flags; \
+			# Ensure source maps are loaded from the correct URL on the web.
+			# Without this, browsers will try the wasm:// protocol and never load the source map.
+			if [ "$EMSCRIPTEN_ENVIRONMENT" = "web" ]; then \
+				export PHP_VERSION_ESCAPED="${PHP_VERSION//./_}"; \
+				echo -n " --source-map-base http://127.0.0.1:5400/@fs${OUTPUT_DIR_FOR_SOURCE_MAP_BASE}/${PHP_VERSION_ESCAPED}/" >> /root/.emcc-php-wasm-flags; \
+			fi; \
 		fi; \
 	else \
 		# Preserve symbol names in node.js build – the bundle size doesn't matter as much
@@ -957,6 +962,7 @@ export ASYNCIFY_ONLY=$'"zif_phar_fopen",\
 RUN mkdir /root/output
 COPY ./php/phpwasm-emscripten-library.js /root/phpwasm-emscripten-library.js
 ARG WITH_SOURCEMAPS
+ARG WITH_DEBUG
 RUN set -euxo pipefail; \
 	mkdir -p /build/output; \
 	source /root/emsdk/emsdk_env.sh; \
@@ -996,7 +1002,7 @@ RUN set -euxo pipefail; \
 "_wasm_set_request_uri", \n\
 "_wasm_set_skip_shebang" '"$(cat /root/.EXPORTED_FUNCTIONS)"']'; \
 	export OPTIMIZATION_FLAGS="-O3"; \
-	if [ "${WITH_SOURCEMAPS}" = "yes" ]; then \
+	if [ "${WITH_SOURCEMAPS}" = "yes" ] || [ "${WITH_DEBUG}" = "yes" ]; then \
 		export OPTIMIZATION_FLAGS="-O0"; \
 	fi; \
 	emcc $OPTIMIZATION_FLAGS \
@@ -1156,6 +1162,9 @@ RUN set -euxo pipefail; \
 			# Make the source map paths relative to the .wasm file, not the build directory
 			sed -i 's#"\.\./\.\./root/#"#g' /root/output/php.wasm.map; \
 			mv /root/output/php.wasm.map "/root/output/${PHP_VERSION_ESCAPED}/php.wasm.map"; \
+		fi; \
+		if [ "${WITH_SOURCEMAPS}" = "yes" ] || [ "${WITH_DEBUG}" = "yes" ]; then \
+			# Make PHP source available for use with step debugger
 			rm -rf /root/php-src/.git; \
 			cp -r /root/php-src "/root/output/${PHP_VERSION_ESCAPED}/php-src"; \
 			cp -r /root/emsdk/upstream/emscripten/system "/root/output/${PHP_VERSION_ESCAPED}/php-src/system"; \