Merge pull request github#11029 from github/redsun82/swift-filtered-debugging

Swift: add possibility to run the extractor under an env-specified tool

Author: redsun82

swift/README.md

@@ -24,7 +24,9 @@ Notice you can run `bazel run :create-extractor-pack` if you already are in the
 
 Using `codeql ... --search-path=swift/extractor-pack` will then pick up the Swift extractor. You can also use
 `--search-path=.`, as the extractor pack is mentioned in the root `codeql-workspace.yml`. Alternatively, you can
-set up the search path in [the per-user CodeQL configuration file](https://codeql.github.com/docs/codeql-cli/specifying-command-options-in-a-codeql-configuration-file/#using-a-codeql-configuration-file).
+set up the search path
+in [the per-user CodeQL configuration file](https://codeql.github.com/docs/codeql-cli/specifying-command-options-in-a-codeql-configuration-file/#using-a-codeql-configuration-file)
+.
 
 ## Code generation
 
@@ -53,3 +55,30 @@ options. This is known to have issues on non-Linux platforms.
 The `CMakeLists.txt` file allows to load the Swift extractor as a CMake project, which allows integration into a wider
 variety of IDEs. Building with CMake also creates a `compile_commands.json` compilation database that can be picked up
 by even more IDEs. In particular, opening the `swift` directory in VSCode should work.
+
+### Debugging codeql database creation
+
+If you want to debug a specific run of the extractor within an integration test or a complex `codeql database create`
+invocation, you can do so using [`gdbserver`][gdbserver] or [`lldb-server`][lldb-server].
+
+[gdbserver]: https://sourceware.org/gdb/onlinedocs/gdb/gdbserver-man.html
+
+[lldb-server]: https://lldb.llvm.org/man/lldb-server.html
+
+For example with `gdbserver`, you can
+
+```bash
+export CODEQL_EXTRACTOR_SWIFT_RUN_UNDER="gdbserver :1234"
+export CODEQL_EXTRACTOR_SWIFT_RUN_UNDER_FILTER="SomeSwiftSource\.swift"  # can be any regex matching extractor args
+```
+
+before starting the database extraction, and when that source is encountered the extractor will be run under
+a `gdbserver` instance listening on port 1234. You can then attach to the running debugging server from `gdb` or your
+IDE. Please refer to your IDE's instructions for how to set up remote debugging.
+
+In particular for breakpoints to work you might need to setup the following remote path mapping:
+
+| Remote      | Local                                |
+|-------------|--------------------------------------|
+| `swift`     | `/absolute/path/to/codeql/swift`     |
+| `bazel-out` | `/absolute/path/to/codeql/bazel-out` |

swift/extractor/main.cpp

@@ -5,6 +5,8 @@
 #include <vector>
 #include <string>
 #include <iostream>
+#include <regex>
+#include <unistd.h>
 
 #include <swift/Basic/LLVMInitialize.h>
 #include <swift/FrontendTool/FrontendTool.h>
@@ -51,7 +53,52 @@ static void lockOutputSwiftModuleTraps(const codeql::SwiftExtractorConfiguration
   }
 }
 
+static bool checkRunUnderFilter(int argc, char* const* argv) {
+  auto runUnderFilter = getenv("CODEQL_EXTRACTOR_SWIFT_RUN_UNDER_FILTER");
+  if (runUnderFilter == nullptr) {
+    return true;
+  }
+  std::string call = argv[0];
+  for (auto i = 1; i < argc; ++i) {
+    call += ' ';
+    call += argv[i];
+  }
+  std::regex filter{runUnderFilter, std::regex_constants::basic | std::regex_constants::nosubs};
+  return std::regex_search(call, filter);
+}
+
+// if `CODEQL_EXTRACTOR_SWIFT_RUN_UNDER` env variable is set, and either
+// * `CODEQL_EXTRACTOR_SWIFT_RUN_UNDER_FILTER` is not set, or
+// * it is set to a regexp matching any substring of the extractor call
+// then the running process is substituted with the command (and possibly
+// options) stated in `CODEQL_EXTRACTOR_SWIFT_RUN_UNDER`, followed by `argv`.
+// Before calling `exec`, `CODEQL_EXTRACTOR_SWIFT_RUN_UNDER` is unset to avoid
+// unpleasant loops.
+// An example usage is to run the extractor under `gdbserver :1234` when the
+// arguments match a given source file.
+static void checkWhetherToRunUnderTool(int argc, char* const* argv) {
+  assert(argc > 0);
+
+  auto runUnder = getenv("CODEQL_EXTRACTOR_SWIFT_RUN_UNDER");
+  if (runUnder == nullptr || !checkRunUnderFilter(argc, argv)) {
+    return;
+  }
+  std::vector<char*> args;
+  // split RUN_UNDER value by spaces to get args vector
+  for (auto word = std::strtok(runUnder, " "); word != nullptr; word = std::strtok(nullptr, " ")) {
+    args.push_back(word);
+  }
+  // append process args, including extractor executable path
+  args.insert(args.end(), argv, argv + argc);
+  args.push_back(nullptr);
+  // avoid looping on this function
+  unsetenv("CODEQL_EXTRACTOR_SWIFT_RUN_UNDER");
+  execvp(args[0], args.data());
+}
+
 int main(int argc, char** argv) {
+  checkWhetherToRunUnderTool(argc, argv);
+
   if (argc == 1) {
     // TODO: print usage
     return 1;

swift/ql/test/extractor-tests/run_under/Strings.expected

@@ -0,0 +1,2 @@
+| run_under: $CODEQL_EXTRACTOR_SWIFT_ROOT/tools/$CODEQL_PLATFORM/extractor -sdk $CODEQL_EXTRACTOR_SWIFT_ROOT/qltest/$CODEQL_PLATFORM/sdk -c -primary-file filtered_in.swift |
+| run_under: $CODEQL_EXTRACTOR_SWIFT_ROOT/tools/$CODEQL_PLATFORM/extractor -sdk $CODEQL_EXTRACTOR_SWIFT_ROOT/qltest/$CODEQL_PLATFORM/sdk -c -primary-file unfiltered.swift |

swift/ql/test/extractor-tests/run_under/Strings.ql

@@ -0,0 +1,4 @@
+import swift
+
+from StringLiteralExpr s
+select s.getValue()

swift/ql/test/extractor-tests/run_under/filtered_in.swift

@@ -0,0 +1 @@
+//codeql-extractor-env: CODEQL_EXTRACTOR_SWIFT_RUN_UNDER=./run_under.sh CODEQL_EXTRACTOR_SWIFT_RUN_UNDER_FILTER=filtered_in\.swift

swift/ql/test/extractor-tests/run_under/filtered_out.swift

@@ -0,0 +1 @@
+//codeql-extractor-env: CODEQL_EXTRACTOR_SWIFT_RUN_UNDER=./run_under.sh CODEQL_EXTRACTOR_SWIFT_RUN_UNDER_FILTER=filtered_in\.swift

swift/ql/test/extractor-tests/run_under/normal.swift

@@ -0,0 +1,7 @@
+ARGS=$(echo $@ | sed 's='$CODEQL_EXTRACTOR_SWIFT_ROOT'=$CODEQL_EXTRACTOR_SWIFT_ROOT=g; s/'$CODEQL_PLATFORM'/$CODEQL_PLATFORM/g')
+
+cat > $CODEQL_EXTRACTOR_SWIFT_TRAP_DIR/$$.trap << EOF
+string_literal_exprs(*, "run_under: $ARGS")
+EOF
+
+"$@"

swift/ql/test/extractor-tests/run_under/run_under.sh

@@ -0,0 +1 @@
+//codeql-extractor-env: CODEQL_EXTRACTOR_SWIFT_RUN_UNDER=./run_under.sh

swift/ql/test/extractor-tests/run_under/unfiltered.swift

@@ -10,12 +10,14 @@ EXTRACTOR="$CODEQL_EXTRACTOR_SWIFT_ROOT/tools/$CODEQL_PLATFORM/extractor"
 SDK="$CODEQL_EXTRACTOR_SWIFT_ROOT/qltest/$CODEQL_PLATFORM/sdk"
 
 for src in *.swift; do
+  env=()
   opts=(-sdk "$SDK" -c -primary-file "$src")
   opts+=($(sed -n '1 s=//codeql-extractor-options:==p' $src))
   expected_status=$(sed -n 's=//codeql-extractor-expected-status:\s*==p' $src)
   expected_status=${expected_status:-0}
+  env+=($(sed -n '1 s=//codeql-extractor-env:==p' $src))
   echo -e "calling extractor with flags: ${opts[@]}\n" >> $QLTEST_LOG
-  "$EXTRACTOR" "${opts[@]}" >> $QLTEST_LOG 2>&1
+  env "${env[@]}" "$EXTRACTOR" "${opts[@]}" >> $QLTEST_LOG 2>&1
   actual_status=$?
   if [[ $actual_status != $expected_status ]]; then
     FAILED=1