Fuzzing: Add a rationale for the current build style

I myself was confused about the current build setup of the fuzzing targets
while setting up clusterfuzzlite, so added some comments.

Author: kateinoigakukun

FuzzTesting/Package.swift

@@ -5,8 +5,25 @@ import PackageDescription
 let package = Package(
     name: "FuzzTesting",
     products: [
+        // Discussion: Why we build libraries instead of executables linking libFuzzer?
+        //
+        // First, libclang_rt.fuzzer.a defines the main function for the fuzzing process
+        // and object files given by the user are expected not to have a "main" function
+        // to avoid conflicts.
+        // Fortunately, SwiftPM asks the compiler frontend to define the main entrypoint as
+        // `<module_name>_main` for testing executable targets (`-entry-point-function-name`)
+        // so object files of `executableTarget` targets are capable of being linked with
+        // libclang_rt.fuzzer.a.
+        // However, at link-time, SwiftPM asks the linker to rename the `<module_name>_main`
+        // symbol back to `main` for the final executable (`--defsym main=<module_name>_main`)
+        // and gold linker respects the renamed "main" symbol rather than the one defined in
+        // libclang_rt.fuzzer.a, so the final executable does not start the fuzzing process.
+        //
+        // Instead of relying on the SwiftPM's linking process, we build libraries defining
+        // fuzzing target functions and manually link them with fuzzing runtime libraries.
         .library(name: "FuzzTranslator", type: .static, targets: ["FuzzTranslator"]),
         .library(name: "FuzzExecute", type: .static, targets: ["FuzzExecute"]),
+        // FuzzDifferential is not a libFuzzer-based target, so we build it as an executable.
         .executable(name: "FuzzDifferential", targets: ["FuzzDifferential"]),
     ],
     dependencies: [

FuzzTesting/fuzz.py

@@ -101,6 +101,8 @@ def build(args, runner: CommandRunner):
     ], check=True)
 
     print('Building fuzzer executable')
+    # See "Discussion" in Package.swift for why we need to manually link
+    # the library product.
     output = executable_path(args.target_name)
     runner.run([
         'swiftc', f'./.build/debug/lib{args.target_name}.a', '-g',