Debugging

We debug mod_pagespeed with 'gdb'. Most of us use Emacs to edit our code and to drive gdb. Other alternatives include using a GUI wrapper for gdb like xgdb, or an IDE like Eclipse.

Unit Tests

We link all the tests together into one executable, which makes it fast to build the entire set of them on a single CPU. You can select individual tests to run from the 'make' command line with:

make apache_test TEST=pattern

eg:

make apache_test "TEST=CssCombine*.Cross"

Note that this builds all the tests, but it only runs the ones that match the wildcard pattern. To debug the test, use:

M-x gdb
Run gdb (like this): gdb64 --annotate=3 
/usr/local/google/home/$USER/modpagespeed/$CLIENT/src/out/Debug/TEST_BINARY
(gdb) run --gtest_filter="CssCombine*.Cross*"
...

Where TEST_BINARY is either mod_pagespeed_test or pagespeed_automatic_test. mod_pagespeed_test has tests for code that needs to be linked with the Apache Runtime Library, such as AprMemCacheTest or SerfUrlAyncFetcherTest. pagespeed_automatic_test has all the tests for the rest

Note: I strongly recommend you debug with Emacs. Also use Emacs for compiling, shell interaction, and just about everything else. If for some reason you don't want to debug with Emacs then you probably want to omit "--annotate=3" from the gdb command line.

Debugging in the Apache server

The trickiest part of debugging the Aapche server is that it has a multi-process architecture, at least in the pre-fork MPM. The main apache process forks subprocesses to service requests; not much happens by default in the root process. To debug mod_pagespeed you must run Apache in single-process mode via "-X":

M-x gdb
Run gdb (like this): gdb64 --annotate=3 /usr/local/apache2/bin/httpd
(gdb) run -X
...

One challenge of debugging Apache in this mode is that if mod_pagespeed needs to do a URL fetch to the Apache server itself, the request cannot be serviced until the current request completes, as there is only one process per request. This does not typically happen but it's good to be aware of it.

For this reason, it is usually better to debug Apache using the Worker MPM.

Debugging the Nginx server

Nginx is event-looped based, which means even if you restrict it to single process mode it can still do loopback fetches. By default we run nginx in a single process, so to debug it you just need to identify the PID of the worker process and attach to it:

gdb -tui -p $(ps aux | grep nginx | grep worker | awk '{print $2}')

System tests

When debugging system tests, the ones in .sh files, you want to restrict which tests run so you don't have to wait through all of them:

TEST_TO_RUN=resource_content_type_html make apache_debug_smoke_test

This only works for tests that have been converted to run_test, so everything except ngx_pagespeed/nginx_system_test.sh works.