build: Propagate some comments from Autotools build into Meson

Comments like these represent hard-won knowledge which we should not
discard.

Signed-off-by: Simon McVittie <smcv@collabora.com>

meson.build

@@ -203,6 +203,7 @@ foreach type : int_types
         arch_config.set('DBUS_INT64_CONSTANT', type.get('type_c'))
         arch_config.set('DBUS_UINT64_CONSTANT', type.get('type_u_c'))
         if platform_windows
+          # MSVCRT.dll printf() doesn't support %lld
           arch_config.set('DBUS_INT64_MODIFIER', 'I64')
         else
           arch_config.set('DBUS_INT64_MODIFIER', type.get('type_m'))
@@ -834,20 +835,30 @@ if session_socket_dir == ''
 endif
 config.set_quoted('DBUS_SESSION_SOCKET_DIR', session_socket_dir)
 
+# This must be a listening address. It doesn't necessarily need to be an
+# address you can connect to - it can be something vague like
+# "nonce-tcp:".
 session_bus_listen_address = get_option('dbus_session_bus_listen_address')
 if session_bus_listen_address == ''
     if platform_windows
+        # On Windows, you can (and should) listen on autolaunch addresses,
+        # because autolaunching is not the same as X11 autolaunching.
         session_bus_listen_address = 'autolaunch:'
     elif use_launchd
+        # macOS default is to use launchd
         session_bus_listen_address = 'launchd:env=DBUS_LAUNCHD_SESSION_BUS_SOCKET'
     else
+        # The default on all other Unix platforms (notably Linux)
+        # is to create a randomly named socket in /tmp or similar
         session_bus_listen_address = 'unix:tmpdir=@0@'.format(session_socket_dir)
     endif
 endif
 data_config.set('DBUS_SESSION_BUS_LISTEN_ADDRESS', session_bus_listen_address)
 
 
-
+# This must be an address you can connect to. It doesn't necessarily
+# need to be an address you can listen on - it can be "autolaunch:",
+# even on Unix.
 session_bus_connect_address = get_option('dbus_session_bus_connect_address')
 if session_bus_connect_address == ''
     session_bus_connect_address = 'autolaunch:'
@@ -896,6 +907,8 @@ else
       '-Wno-unused-parameter',
       '-Wchar-subscripts',
       '-Wfloat-equal',
+      # On Windows, we expect to be using msvcrt.dll-compatible printf
+      # (%I64u instead of %llu)
       '-D__USE_MINGW_ANSI_STDIO=0',
   ]
 

test/meson.build

@@ -48,6 +48,7 @@ test_env.set('HOME',                meson.project_source_root() / 'dbus')
 test_env.set('DBUS_TEST_SRCDIR',    meson.current_source_dir())
 
 test_env.set('DBUS_TOP_BUILDDIR',   meson.project_build_root())
+# Tests in bus/config-parser.c rely on this specific value
 test_env.set('DBUS_TEST_BUILDDIR',  meson.current_build_dir())
 test_env.set('DBUS_TEST_EXEC',      meson.current_build_dir())
 test_env.set('DBUS_TEST_DATA',      meson.current_build_dir() / 'data')
@@ -61,7 +62,7 @@ if platform_unix
     test_env.set('DBUS_TEST_DBUS_UUIDGEN', dbus_uuidgen.full_path())
 endif
 
-
+# Tests in bus/config-parser.c rely on these specific values for XDG_*
 test_env.set('XDG_DATA_HOME',       meson.current_build_dir() / 'XDG_DATA_HOME')
 test_env.set('XDG_RUNTIME_DIR',     meson.current_build_dir() / 'XDG_RUNTIME_DIR')
 xdg_data_dirs = [
@@ -137,6 +138,9 @@ test_privserver = executable('test-privserver',
 # This helper is meant to crash, so if we're compiling the rest with
 # AddressSanitizer, we need to stop it from catching the SIGSEGV and
 # turning it into _exit(1).
+# We have to compile a separate copy of disable-crash-handling.c for
+# test-segfault rather than using libdbus-testutils, because
+# otherwise it would fail to link when using the AddressSanitizer.
 test_segfault = executable('test-segfault',
     'test-segfault.c', 'disable-crash-handling.c',
     include_directories: root_include,
@@ -521,6 +525,7 @@ foreach test: tests
         install_dir: test_exec_dir,
     )
 
+    # Some binaries are used in tests but are not themselves tests
     if test_now
         test(name,
             test_exe,
@@ -546,6 +551,7 @@ if platform_unix and use_glib
         {   'name': 'test-apparmor-activation.sh' },
     ]
 
+    # Testing dbus-launch relies on special code in that binary.
     if embedded_tests
         scripts += { 'name': 'test-dbus-launch-eval.sh' }
     endif