subprojects: Prepare for release

Expose Device.override_option() for overriding backend-specific
options on a device.

Overrides apply when establishing a host session. If one already
exists, changes take effect on the next connection.

examples/child_gating.py

@@ -42,18 +42,16 @@ class Application:
         print("✔ enable_child_gating()")
         session.enable_child_gating()
         print("✔ create_script()")
-        script = session.create_script(
-            """\
-Interceptor.attach(Module.getExportByName(null, 'open'), {
-  onEnter: function (args) {
+        script = session.create_script("""\
+Interceptor.attach(Module.getGlobalExportByName('open'), {
+  onEnter(args) {
     send({
       type: 'open',
-      path: Memory.readUtf8String(args[0])
+      path: args[0].readUtf8String()
     });
   }
 });
-"""
-        )
+""")
         script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
         print("✔ load()")
         script.load()

examples/inject_library/inject_blob.py

@@ -15,7 +15,7 @@ def on_uninjected(id):
     print("on_uninjected id=%u" % id)
 
 
-(target, library_path) = sys.argv[1:]
+target, library_path = sys.argv[1:]
 
 device = frida.get_local_device()
 device.on("uninjected", on_uninjected)

examples/inject_library/inject_file.py

@@ -15,7 +15,7 @@ def on_uninjected(id):
     print("on_uninjected id=%u" % id)
 
 
-(target, library_path) = sys.argv[1:]
+target, library_path = sys.argv[1:]
 
 device = frida.get_local_device()
 device.on("uninjected", on_uninjected)

examples/rpc.py

@@ -1,8 +1,7 @@
 import frida
 
 session = frida.attach("Twitter")
-script = session.create_script(
-    """\
+script = session.create_script("""\
 rpc.exports = {
   hello: function () {
     return 'Hello';
@@ -11,8 +10,7 @@ rpc.exports = {
     oops;
   }
 };
-"""
-)
+""")
 script.load()
 api = script.exports_sync
 print("api.hello() =>", api.hello())

examples/session_persist_timeout.py

@@ -22,8 +22,7 @@ class Application:
         self._session = session
         session.on("detached", lambda *args: self._reactor.schedule(lambda: self._on_detached(*args)))
 
-        script = session.create_script(
-            """
+        script = session.create_script("""
 let _puts = null;
 
 Interceptor.attach(DebugSymbol.getFunctionByName('f'), {
@@ -48,8 +47,7 @@ function puts(s) {
   }
   _puts(Memory.allocUtf8String(s));
 }
-"""
-        )
+""")
         self._script = script
         script.on("message", lambda *args: self._reactor.schedule(lambda: self._on_message(*args)))
         script.load()

examples/spawn_gating.py

@@ -0,0 +1,78 @@
+import threading
+
+from frida_tools.application import Reactor
+
+import frida
+
+
+class Application:
+    def __init__(self):
+        self._stop_requested = threading.Event()
+        self._reactor = Reactor(run_until_return=lambda reactor: self._stop_requested.wait())
+
+        self._device = frida.get_usb_device()
+        self._sessions = set()
+        self._sessions_lock = threading.Lock()
+
+        self._device.on("spawn-added", lambda spawn: self._reactor.schedule(lambda: self._on_spawn_added(spawn)))
+        self._device.on("spawn-removed", lambda spawn: self._reactor.schedule(lambda: self._on_spawn_removed(spawn)))
+
+    def run(self):
+        self._reactor.schedule(lambda: self._start())
+        self._reactor.run()
+
+    def _start(self):
+        self._device.enable_spawn_gating()
+
+    def _instrument(self, pid):
+        print(f"✔ attach(pid={pid})")
+        session = self._device.attach(pid)
+        session.on("detached", lambda reason: self._reactor.schedule(lambda: self._on_detached(pid, session, reason)))
+        print("✔ create_script()")
+        script = session.create_script("""\
+const puts = new NativeFunction(Module.getGlobalExportByName('puts'), 'int', ['pointer']);
+puts(Memory.allocUtf8String('Hello from Frida agent'));
+Interceptor.attach(Module.getGlobalExportByName('open'), {
+  onEnter(args) {
+    send({
+      type: 'open',
+      path: args[0].readUtf8String()
+    });
+  }
+});
+""")
+        script.on("message", lambda message, data: self._reactor.schedule(lambda: self._on_message(pid, message)))
+        print("✔ load()")
+        script.load()
+        print(f"✔ resume(pid={pid})")
+        self._device.resume(pid)
+        with self._sessions_lock:
+            self._sessions.add(session)
+
+    def _on_spawn_added(self, spawn):
+        print(f"⚡ spawn_added: {spawn}")
+        t = threading.Thread(target=self._handle_spawn, args=(spawn,))
+        t.start()
+
+    def _handle_spawn(self, spawn):
+        if "/bin/ls" in spawn.identifier:
+            self._instrument(spawn.pid)
+        else:
+            pid = spawn.pid
+            print(f"✔ resume(pid={pid})")
+            self._device.resume(pid)
+
+    def _on_spawn_removed(self, spawn):
+        print(f"⚡ spawn_removed: {spawn}")
+
+    def _on_detached(self, pid, session, reason):
+        print(f"⚡ detached: pid={pid}, reason='{reason}'")
+        with self._sessions_lock:
+            self._sessions.remove(session)
+
+    def _on_message(self, pid, message):
+        print(f"⚡ message: pid={pid}, payload={message['payload']}")
+
+
+app = Application()
+app.run()

frida/_frida/__init__.pyi

@@ -754,8 +754,13 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> str:
         """
         Build an agent.
@@ -766,8 +771,13 @@ class Compiler(Object):
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
+        output_format: Optional[str] = None,
+        bundle_format: Optional[str] = None,
+        type_check: Optional[str] = None,
         source_maps: Optional[str] = None,
         compression: Optional[str] = None,
+        platform: Optional[str] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> None:
         """
         Continuously build an agent.
@@ -803,7 +813,9 @@ class PackageManager(Object):
     def install(
         self,
         project_root: Optional[str] = None,
+        role: Optional[str] = None,
         specs: Optional[Sequence[str]] = None,
+        omits: Optional[Sequence[str]] = None,
     ) -> PackageInstallResult:
         """
         Install one or more packages.

frida/_frida/extension.c

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2013-2023 Ole André Vadla Ravnås <oleavr@nowsecure.com>
+ * Copyright (C) 2013-2026 Ole André Vadla Ravnås <oleavr@nowsecure.com>
  * Copyright (C) 2024 Håvard Sørbø <havard@hsorbo.no>
  *
  * Licence: wxWindows Library Licence, Version 3.1
@@ -378,6 +378,7 @@ static PyObject * PyGObject_marshal_variant (GVariant * variant);
 static PyObject * PyGObject_marshal_variant_byte_array (GVariant * variant);
 static PyObject * PyGObject_marshal_variant_dict (GVariant * variant);
 static PyObject * PyGObject_marshal_variant_array (GVariant * variant);
+static PyObject * PyGObject_marshal_variant_tuple (GVariant * variant);
 static gboolean PyGObject_unmarshal_variant (PyObject * value, GVariant ** variant);
 static gboolean PyGObject_unmarshal_variant_from_mapping (PyObject * mapping, GVariant ** variant);
 static gboolean PyGObject_unmarshal_variant_from_sequence (PyObject * sequence, GVariant ** variant);
@@ -403,6 +404,7 @@ static void PyDevice_init_from_handle (PyDevice * self, FridaDevice * handle);
 static void PyDevice_dealloc (PyDevice * self);
 static PyObject * PyDevice_repr (PyDevice * self);
 static PyObject * PyDevice_is_lost (PyDevice * self);
+static PyObject * PyDevice_override_option (PyDevice * self, PyObject * args, PyObject * kw);
 static PyObject * PyDevice_query_system_parameters (PyDevice * self);
 static PyObject * PyDevice_get_frontmost_application (PyDevice * self, PyObject * args, PyObject * kw);
 static PyObject * PyDevice_enumerate_applications (PyDevice * self, PyObject * args, PyObject * kw);
@@ -533,7 +535,8 @@ static void PyCompiler_dealloc (PyCompiler * self);
 static PyObject * PyCompiler_build (PyCompiler * self, PyObject * args, PyObject * kw);
 static PyObject * PyCompiler_watch (PyCompiler * self, PyObject * args, PyObject * kw);
 static gboolean PyCompiler_set_options (FridaCompilerOptions * options, const gchar * project_root_value, const gchar * output_format_value,
-    const gchar * bundle_format_value, const gchar * type_check_value, const gchar * source_maps_value, const gchar * compression_value);
+    const gchar * bundle_format_value, const gchar * type_check_value, const gchar * source_maps_value, const gchar * compression_value,
+    const gchar * platform_value, PyObject * externals_value);
 
 static int PyPackageManager_init (PyPackageManager * self, PyObject * args, PyObject * kw);
 static void PyPackageManager_dealloc (PyPackageManager * self);
@@ -542,7 +545,8 @@ static PyObject * PyPackageManager_get_registry (PyPackageManager * self, void *
 static int PyPackageManager_set_registry (PyPackageManager * self, PyObject * val, void * closure);
 static PyObject * PyPackageManager_search (PyPackageManager * self, PyObject * args, PyObject * kw);
 static PyObject * PyPackageManager_install (PyPackageManager * self, PyObject * args, PyObject * kw);
-static FridaPackageInstallOptions * PyPackageManager_parse_install_options (const gchar * project_root, PyObject * specs_value);
+static FridaPackageInstallOptions * PyPackageManager_parse_install_options (const gchar * project_root, const char * role_value,
+    PyObject * specs_value, PyObject * omits_value);
 
 static PyObject * PyPackage_new_take_handle (FridaPackage * handle);
 static int PyPackage_init (PyPackage * self, PyObject * args, PyObject * kw);
@@ -617,6 +621,7 @@ static PyMethodDef PyDeviceManager_methods[] =
 static PyMethodDef PyDevice_methods[] =
 {
   { "is_lost", (PyCFunction) PyDevice_is_lost, METH_NOARGS, "Query whether the device has been lost." },
+  { "override_option", (PyCFunction) PyDevice_override_option, METH_VARARGS | METH_KEYWORDS, "Override a backend-specific option." },
   { "query_system_parameters", (PyCFunction) PyDevice_query_system_parameters, METH_NOARGS, "Returns a dictionary of information about the host system." },
   { "get_frontmost_application", (PyCFunction) PyDevice_get_frontmost_application, METH_VARARGS | METH_KEYWORDS, "Get details about the frontmost application." },
   { "enumerate_applications", (PyCFunction) PyDevice_enumerate_applications, METH_VARARGS | METH_KEYWORDS, "Enumerate applications." },
@@ -1747,10 +1752,20 @@ PyGObject_marshal_variant (GVariant * variant)
   {
     case G_VARIANT_CLASS_STRING:
       return PyGObject_marshal_string (g_variant_get_string (variant, NULL));
+    case G_VARIANT_CLASS_BYTE:
+      return PyLong_FromLong (g_variant_get_byte (variant));
+    case G_VARIANT_CLASS_INT16:
+      return PyLong_FromLong (g_variant_get_int16 (variant));
+    case G_VARIANT_CLASS_UINT16:
+      return PyLong_FromUnsignedLong (g_variant_get_uint16 (variant));
+    case G_VARIANT_CLASS_INT32:
+      return PyLong_FromLong (g_variant_get_int32 (variant));
+    case G_VARIANT_CLASS_UINT32:
+      return PyLong_FromUnsignedLong (g_variant_get_uint32 (variant));
     case G_VARIANT_CLASS_INT64:
       return PyLong_FromLongLong (g_variant_get_int64 (variant));
     case G_VARIANT_CLASS_UINT64:
-      return PyLong_FromLongLong (g_variant_get_uint64 (variant));
+      return PyLong_FromUnsignedLongLong (g_variant_get_uint64 (variant));
     case G_VARIANT_CLASS_DOUBLE:
       return PyFloat_FromDouble (g_variant_get_double (variant));
     case G_VARIANT_CLASS_BOOLEAN:
@@ -1763,6 +1778,19 @@ PyGObject_marshal_variant (GVariant * variant)
         return PyGObject_marshal_variant_dict (variant);
 
       return PyGObject_marshal_variant_array (variant);
+    case G_VARIANT_CLASS_TUPLE:
+      return PyGObject_marshal_variant_tuple (variant);
+    case G_VARIANT_CLASS_VARIANT:
+    {
+      GVariant * inner;
+      PyObject * result;
+
+      inner = g_variant_get_variant (variant);
+      result = PyGObject_marshal_variant (inner);
+      g_variant_unref (inner);
+
+      return result;
+    }
     default:
       break;
   }
@@ -1821,13 +1849,6 @@ PyGObject_marshal_variant_array (GVariant * variant)
 
   for (i = 0; (child = g_variant_iter_next_value (&iter)) != NULL; i++)
   {
-    if (g_variant_is_of_type (child, G_VARIANT_TYPE_VARIANT))
-    {
-      GVariant * inner = g_variant_get_variant (child);
-      g_variant_unref (child);
-      child = inner;
-    }
-
     PyList_SetItem (list, i, PyGObject_marshal_variant (child));
 
     g_variant_unref (child);
@@ -1836,6 +1857,28 @@ PyGObject_marshal_variant_array (GVariant * variant)
   return list;
 }
 
+static PyObject *
+PyGObject_marshal_variant_tuple (GVariant * variant)
+{
+  GVariantIter iter;
+  PyObject * tuple;
+  guint i;
+  GVariant * child;
+
+  g_variant_iter_init (&iter, variant);
+
+  tuple = PyTuple_New (g_variant_iter_n_children (&iter));
+
+  for (i = 0; (child = g_variant_iter_next_value (&iter)) != NULL; i++)
+  {
+    PyTuple_SetItem (tuple, i, PyGObject_marshal_variant (child));
+
+    g_variant_unref (child);
+  }
+
+  return tuple;
+}
+
 static gboolean
 PyGObject_unmarshal_variant (PyObject * value, GVariant ** variant)
 {
@@ -1845,14 +1888,14 @@ PyGObject_unmarshal_variant (PyObject * value, GVariant ** variant)
 
     PyGObject_unmarshal_string (value, &str);
 
-    *variant = g_variant_new_take_string (str);
+    *variant = g_variant_ref_sink (g_variant_new_take_string (str));
 
     return TRUE;
   }
 
   if (PyBool_Check (value))
   {
-    *variant = g_variant_new_boolean (value == Py_True);
+    *variant = g_variant_ref_sink (g_variant_new_boolean (value == Py_True));
 
     return TRUE;
   }
@@ -1865,14 +1908,14 @@ PyGObject_unmarshal_variant (PyObject * value, GVariant ** variant)
     if (l == -1 && PyErr_Occurred ())
       return FALSE;
 
-    *variant = g_variant_new_int64 (l);
+    *variant = g_variant_ref_sink (g_variant_new_int64 (l));
 
     return TRUE;
   }
 
   if (PyFloat_Check (value))
   {
-    *variant = g_variant_new_double (PyFloat_AsDouble (value));
+    *variant = g_variant_ref_sink (g_variant_new_double (PyFloat_AsDouble (value)));
 
     return TRUE;
   }
@@ -1886,7 +1929,7 @@ PyGObject_unmarshal_variant (PyObject * value, GVariant ** variant)
     PyBytes_AsStringAndSize (value, &buffer, &length);
 
     copy = g_memdup2 (buffer, length);
-    *variant = g_variant_new_from_data (G_VARIANT_TYPE_BYTESTRING, copy, length, TRUE, g_free, copy);
+    *variant = g_variant_ref_sink (g_variant_new_from_data (G_VARIANT_TYPE_BYTESTRING, copy, length, TRUE, g_free, copy));
 
     return TRUE;
   }
@@ -1932,12 +1975,13 @@ PyGObject_unmarshal_variant_from_mapping (PyObject * mapping, GVariant ** varian
 
     g_variant_builder_add (&builder, "{sv}", PyBytes_AsString (key_bytes), raw_value);
 
+    g_variant_unref (raw_value);
     Py_DecRef (key_bytes);
   }
 
   Py_DecRef (items);
 
-  *variant = g_variant_builder_end (&builder);
+  *variant = g_variant_ref_sink (g_variant_builder_end (&builder));
 
   return TRUE;
 
@@ -1960,6 +2004,31 @@ PyGObject_unmarshal_variant_from_sequence (PyObject * sequence, GVariant ** vari
 
   is_tuple = PyTuple_Check (sequence);
 
+  if (is_tuple && PyTuple_Size (sequence) == 2)
+  {
+    gchar * type;
+    gboolean is_uint64_cast;
+
+    if (!PyGObject_unmarshal_string (PyTuple_GetItem (sequence, 0), &type))
+      return FALSE;
+
+    is_uint64_cast = strcmp (type, "uint64") == 0;
+
+    g_free (type);
+
+    if (is_uint64_cast)
+    {
+      unsigned PY_LONG_LONG l;
+
+      l = PyLong_AsUnsignedLongLong (PyTuple_GetItem (sequence, 1));
+      if (l == (unsigned PY_LONG_LONG) -1 && PyErr_Occurred ())
+        return FALSE;
+
+      *variant = g_variant_ref_sink (g_variant_new_uint64 (l));
+      return TRUE;
+    }
+  }
+
   g_variant_builder_init (&builder, is_tuple ? G_VARIANT_TYPE_TUPLE : G_VARIANT_TYPE ("av"));
 
   n = PySequence_Length (sequence);
@@ -1982,10 +2051,11 @@ PyGObject_unmarshal_variant_from_sequence (PyObject * sequence, GVariant ** vari
     else
       g_variant_builder_add (&builder, "v", raw_value);
 
+    g_variant_unref (raw_value);
     Py_DecRef (val);
   }
 
-  *variant = g_variant_builder_end (&builder);
+  *variant = g_variant_ref_sink (g_variant_builder_end (&builder));
 
   return TRUE;
 
@@ -2453,6 +2523,33 @@ PyDevice_is_lost (PyDevice * self)
   return PyBool_FromLong (is_lost);
 }
 
+static PyObject *
+PyDevice_override_option (PyDevice * self, PyObject * args, PyObject * kw)
+{
+  static char * keywords[] = { "name", "value", NULL };
+  const char * name;
+  PyObject * value;
+  GVariant * raw_value;
+  GError * error = NULL;
+
+  if (!PyArg_ParseTupleAndKeywords (args, kw, "sO", keywords, &name, &value))
+    return NULL;
+
+  if (!PyGObject_unmarshal_variant (value, &raw_value))
+    return NULL;
+
+  Py_BEGIN_ALLOW_THREADS
+  frida_device_override_option (PY_GOBJECT_HANDLE (self), name, raw_value, &error);
+  Py_END_ALLOW_THREADS
+
+  g_variant_unref (raw_value);
+
+  if (error != NULL)
+    return PyFrida_raise (error);
+
+  PyFrida_RETURN_NONE;
+}
+
 static PyObject *
 PyDevice_query_system_parameters (PyDevice * self)
 {
@@ -2885,7 +2982,7 @@ PyDevice_spawn (PyDevice * self, PyObject * args, PyObject * kw)
         goto invalid_dict_value;
       }
 
-      g_hash_table_insert (aux, raw_key, g_variant_ref_sink (raw_value));
+      g_hash_table_insert (aux, raw_key, raw_value);
     }
   }
 
@@ -4903,8 +5000,8 @@ static PyObject *
 PyCompiler_build (PyCompiler * self, PyObject * args, PyObject * kw)
 {
   PyObject * result;
-  static char * keywords[] =
-      { "entrypoint", "project_root", "output_format", "bundle_format", "type_check", "source_maps", "compression", NULL };
+  static char * keywords[] = { "entrypoint", "project_root", "output_format", "bundle_format", "type_check", "source_maps", "compression",
+    "platform", "externals", NULL };
   const char * entrypoint;
   const char * project_root = NULL;
   const char * output_format = NULL;
@@ -4912,17 +5009,19 @@ PyCompiler_build (PyCompiler * self, PyObject * args, PyObject * kw)
   const char * type_check = NULL;
   const char * source_maps = NULL;
   const char * compression = NULL;
+  const char * platform = NULL;
+  PyObject * externals = NULL;
   FridaBuildOptions * options;
   GError * error = NULL;
   gchar * bundle;
 
-  if (!PyArg_ParseTupleAndKeywords (args, kw, "s|ssssss", keywords, &entrypoint, &project_root, &output_format, &bundle_format, &type_check,
-        &source_maps, &compression))
+  if (!PyArg_ParseTupleAndKeywords (args, kw, "s|sssssssO", keywords, &entrypoint, &project_root, &output_format, &bundle_format,
+        &type_check, &source_maps, &compression, &platform, &externals))
     return NULL;
 
   options = frida_build_options_new ();
   if (!PyCompiler_set_options (FRIDA_COMPILER_OPTIONS (options), project_root, output_format, bundle_format, type_check, source_maps,
-        compression))
+        compression, platform, externals))
     goto invalid_option_value;
 
   Py_BEGIN_ALLOW_THREADS
@@ -4949,8 +5048,8 @@ invalid_option_value:
 static PyObject *
 PyCompiler_watch (PyCompiler * self, PyObject * args, PyObject * kw)
 {
-  static char * keywords[] =
-      { "entrypoint", "project_root", "output_format", "bundle_format", "type_check", "source_maps", "compression", NULL };
+  static char * keywords[] = { "entrypoint", "project_root", "output_format", "bundle_format", "type_check", "source_maps", "compression",
+    "platform", "externals", NULL };
   const char * entrypoint;
   const char * project_root = NULL;
   const char * output_format = NULL;
@@ -4958,16 +5057,18 @@ PyCompiler_watch (PyCompiler * self, PyObject * args, PyObject * kw)
   const char * type_check = NULL;
   const char * source_maps = NULL;
   const char * compression = NULL;
+  const char * platform = NULL;
+  PyObject * externals = NULL;
   FridaWatchOptions * options;
   GError * error = NULL;
 
-  if (!PyArg_ParseTupleAndKeywords (args, kw, "s|ssssss", keywords, &entrypoint, &project_root, &output_format, &bundle_format, &type_check,
-        &source_maps, &compression))
+  if (!PyArg_ParseTupleAndKeywords (args, kw, "s|sssssssO", keywords, &entrypoint, &project_root, &output_format, &bundle_format,
+        &type_check, &source_maps, &compression, &platform, &externals))
     return NULL;
 
   options = frida_watch_options_new ();
   if (!PyCompiler_set_options (FRIDA_COMPILER_OPTIONS (options), project_root, output_format, bundle_format, type_check, source_maps,
-        compression))
+        compression, platform, externals))
     goto invalid_option_value;
 
   Py_BEGIN_ALLOW_THREADS
@@ -4990,7 +5091,8 @@ invalid_option_value:
 
 static gboolean
 PyCompiler_set_options (FridaCompilerOptions * options, const gchar * project_root_value, const gchar * output_format_value,
-    const gchar * bundle_format_value, const gchar * type_check_value, const gchar * source_maps_value, const gchar * compression_value)
+    const gchar * bundle_format_value, const gchar * type_check_value, const gchar * source_maps_value, const gchar * compression_value,
+    const gchar * platform_value, PyObject * externals_value)
 {
   if (project_root_value != NULL)
     frida_compiler_options_set_project_root (options, project_root_value);
@@ -5045,6 +5147,43 @@ PyCompiler_set_options (FridaCompilerOptions * options, const gchar * project_ro
     frida_compiler_options_set_compression (options, compression);
   }
 
+  if (platform_value != NULL)
+  {
+    FridaJsPlatform platform;
+
+    if (!PyGObject_unmarshal_enum (platform_value, FRIDA_TYPE_JS_PLATFORM, &platform))
+      return FALSE;
+
+    frida_compiler_options_set_platform (options, platform);
+  }
+
+  if (externals_value != NULL)
+  {
+    gint n, i;
+
+    n = PySequence_Size (externals_value);
+    if (n == -1)
+      return FALSE;
+
+    for (i = 0; i != n; i++)
+    {
+      PyObject * element;
+      gchar * external = NULL;
+
+      element = PySequence_GetItem (externals_value, i);
+      if (element == NULL)
+        return FALSE;
+      PyGObject_unmarshal_string (element, &external);
+      Py_DecRef (element);
+      if (external == NULL)
+        return FALSE;
+
+      frida_compiler_options_add_external (options, external);
+
+      g_free (external);
+    }
+  }
+
   return TRUE;
 }
 
@@ -5140,16 +5279,18 @@ static PyObject *
 PyPackageManager_install (PyPackageManager * self, PyObject * args, PyObject * kw)
 {
   FridaPackageInstallResult * result;
-  static char * keywords[] = { "project_root", "specs", NULL };
+  static char * keywords[] = { "project_root", "role", "specs", "omits", NULL };
   const char * project_root = NULL;
+  const char * role_value = NULL;
   PyObject * specs = NULL;
+  PyObject * omits = NULL;
   FridaPackageInstallOptions * options;
   GError * error = NULL;
 
-  if (!PyArg_ParseTupleAndKeywords (args, kw, "|sO", keywords, &project_root, &specs))
+  if (!PyArg_ParseTupleAndKeywords (args, kw, "|ssOO", keywords, &project_root, &role_value, &specs, &omits))
     return NULL;
 
-  options = PyPackageManager_parse_install_options (project_root, specs);
+  options = PyPackageManager_parse_install_options (project_root, role_value, specs, omits);
 
   Py_BEGIN_ALLOW_THREADS
   result = frida_package_manager_install_sync (PY_GOBJECT_HANDLE (self), options, g_cancellable_get_current (), &error);
@@ -5164,7 +5305,7 @@ PyPackageManager_install (PyPackageManager * self, PyObject * args, PyObject * k
 }
 
 static FridaPackageInstallOptions *
-PyPackageManager_parse_install_options (const gchar * project_root, PyObject * specs_value)
+PyPackageManager_parse_install_options (const gchar * project_root, const char * role_value, PyObject * specs_value, PyObject * omits_value)
 {
   FridaPackageInstallOptions * options;
 
@@ -5173,6 +5314,16 @@ PyPackageManager_parse_install_options (const gchar * project_root, PyObject * s
   if (project_root != NULL)
     frida_package_install_options_set_project_root (options, project_root);
 
+  if (role_value != NULL)
+  {
+    FridaPackageRole role;
+
+    if (!PyGObject_unmarshal_enum (role_value, FRIDA_TYPE_PACKAGE_ROLE, &role))
+      goto propagate_error;
+
+    frida_package_install_options_set_role (options, role);
+  }
+
   if (specs_value != NULL)
   {
     gint n, i;
@@ -5195,6 +5346,37 @@ PyPackageManager_parse_install_options (const gchar * project_root, PyObject * s
         goto propagate_error;
 
       frida_package_install_options_add_spec (options, spec);
+
+      g_free (spec);
+    }
+  }
+
+  if (omits_value != NULL)
+  {
+    gint n, i;
+
+    n = PySequence_Size (omits_value);
+    if (n == -1)
+      goto propagate_error;
+
+    for (i = 0; i != n; i++)
+    {
+      PyObject * element;
+      gchar * str = NULL;
+      FridaPackageRole role;
+
+      element = PySequence_GetItem (omits_value, i);
+      if (element == NULL)
+        goto propagate_error;
+      PyGObject_unmarshal_string (element, &str);
+      Py_DecRef (element);
+      if (str == NULL)
+        goto propagate_error;
+
+      if (!PyGObject_unmarshal_enum (str, FRIDA_TYPE_PACKAGE_ROLE, &role))
+        goto propagate_error;
+
+      frida_package_install_options_add_omit (options, role);
     }
   }
 

frida/core.py

@@ -33,10 +33,15 @@ if sys.version_info >= (3, 8):
 else:
     from typing_extensions import Literal, TypedDict
 
-if sys.version_info >= (3, 11):
-    from typing import NotRequired
+if sys.version_info >= (3, 10):
+    from typing import ParamSpec
 else:
-    from typing_extensions import NotRequired
+    from typing_extensions import ParamSpec
+
+if sys.version_info >= (3, 11):
+    from typing import NotRequired, cast
+else:
+    from typing_extensions import NotRequired, cast
 
 from . import _frida
 
@@ -72,15 +77,18 @@ def _filter_missing_kwargs(d: MutableMapping[Any, Any]) -> None:
             d.pop(key)
 
 
-R = TypeVar("R")
+P = ParamSpec("P")
+R = TypeVar("R", covariant=True)
 
 
-def cancellable(f: Callable[..., R]) -> Callable[..., R]:
+def cancellable(f: Callable[P, R]) -> Callable[P, R]:
+    # currently there is no way to type properly the extended callable with optional cancellable parameter
+    # ref: https://github.com/python/typing/discussions/1905#discussioncomment-11696995
     @functools.wraps(f)
-    def wrapper(*args: Any, **kwargs: Any) -> R:
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
         cancellable = kwargs.pop("cancellable", None)
         if cancellable is not None:
-            with cancellable:
+            with cast(Cancellable, cancellable):
                 return f(*args, **kwargs)
 
         return f(*args, **kwargs)
@@ -351,9 +359,6 @@ class Script:
     @overload
     def on(self, signal: Literal["message"], callback: ScriptMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -370,9 +375,6 @@ class Script:
     @overload
     def off(self, signal: Literal["message"], callback: ScriptMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -693,34 +695,22 @@ class Session:
         _filter_missing_kwargs(kwargs)
         return PortalMembership(self._impl.join_portal(address, **kwargs))
 
-    @overload
     def on(
         self,
         signal: Literal["detached"],
         callback: SessionDetachedCallback,
-    ) -> None: ...
-
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def on(self, signal: str, callback: Callable[..., Any]) -> None:
+    ) -> None:
         """
         Add a signal handler
         """
 
         self._impl.on(signal, callback)
 
-    @overload
     def off(
         self,
         signal: Literal["detached"],
         callback: SessionDetachedCallback,
-    ) -> None: ...
-
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def off(self, signal: str, callback: Callable[..., Any]) -> None:
+    ) -> None:
         """
         Remove a signal handler
         """
@@ -763,9 +753,6 @@ class Bus:
     @overload
     def on(self, signal: Literal["message"], callback: BusMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -782,9 +769,6 @@ class Bus:
     @overload
     def off(self, signal: Literal["message"], callback: BusMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -842,9 +826,6 @@ class Service:
     @overload
     def on(self, signal: Literal["message"], callback: ServiceMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -858,9 +839,6 @@ class Service:
     @overload
     def off(self, signal: Literal["message"], callback: ServiceMessageCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -905,6 +883,14 @@ class Device:
 
         return self._impl.is_lost()
 
+    @cancellable
+    def override_option(self, name: str, value: Any) -> None:
+        """
+        Override a backend-specific option
+        """
+
+        self._impl.override_option(name, value)
+
     @cancellable
     def query_system_parameters(self) -> Dict[str, Any]:
         """
@@ -1144,9 +1130,6 @@ class Device:
     @overload
     def on(self, signal: Literal["lost"], callback: DeviceLostCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1178,9 +1161,6 @@ class Device:
     @overload
     def off(self, signal: Literal["lost"], callback: DeviceLostCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -1298,9 +1278,6 @@ class DeviceManager:
     @overload
     def on(self, signal: Literal["changed"], callback: DeviceManagerChangedCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1317,9 +1294,6 @@ class DeviceManager:
     @overload
     def off(self, signal: Literal["changed"], callback: DeviceManagerChangedCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Remove a signal handler
@@ -1344,7 +1318,7 @@ class EndpointParameters:
         _filter_missing_kwargs(kwargs)
 
         if authentication is not None:
-            (auth_scheme, auth_data) = authentication
+            auth_scheme, auth_data = authentication
             if auth_scheme == "token":
                 kwargs["auth_token"] = auth_data
             elif auth_scheme == "callback":
@@ -1490,9 +1464,6 @@ class PortalService:
     @overload
     def on(self, signal: Literal["message"], callback: PortalServiceMessageCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
         """
         Add a signal handler
@@ -1554,6 +1525,13 @@ CompilerFinishedCallback = Callable[[], None]
 CompilerOutputCallback = Callable[[str], None]
 CompilerDiagnosticsCallback = Callable[[List[CompilerDiagnostic]], None]
 
+CompilerOutputFormat = Literal["unescaped", "hex-bytes", "c-string"]
+CompilerBundleFormat = Literal["esm", "iife"]
+CompilerTypeCheck = Literal["full", "none"]
+CompilerSourceMaps = Literal["included", "omitted"]
+CompilerCompression = Literal["none", "terser"]
+CompilerPlatform = Literal["neutral", "gum", "browser"]
+
 
 class Compiler:
     def __init__(self) -> None:
@@ -1567,19 +1545,23 @@ class Compiler:
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        output_format: Optional[str] = None,
-        bundle_format: Optional[str] = None,
-        type_check: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> str:
-        kwargs = {
+        kwargs: dict[str, Any] = {
             "project_root": project_root,
             "output_format": output_format,
             "bundle_format": bundle_format,
             "type_check": type_check,
             "source_maps": source_maps,
             "compression": compression,
+            "platform": platform,
+            "externals": externals,
         }
         _filter_missing_kwargs(kwargs)
         return self._impl.build(entrypoint, **kwargs)
@@ -1589,19 +1571,23 @@ class Compiler:
         self,
         entrypoint: str,
         project_root: Optional[str] = None,
-        output_format: Optional[str] = None,
-        bundle_format: Optional[str] = None,
-        type_check: Optional[str] = None,
-        source_maps: Optional[str] = None,
-        compression: Optional[str] = None,
+        output_format: Optional[CompilerOutputFormat] = None,
+        bundle_format: Optional[CompilerBundleFormat] = None,
+        type_check: Optional[CompilerTypeCheck] = None,
+        source_maps: Optional[CompilerSourceMaps] = None,
+        compression: Optional[CompilerCompression] = None,
+        platform: Optional[CompilerPlatform] = None,
+        externals: Optional[Sequence[str]] = None,
     ) -> None:
-        kwargs = {
+        kwargs: dict[str, Any] = {
             "project_root": project_root,
             "output_format": output_format,
             "bundle_format": bundle_format,
             "type_check": type_check,
             "source_maps": source_maps,
             "compression": compression,
+            "platform": platform,
+            "externals": externals,
         }
         _filter_missing_kwargs(kwargs)
         return self._impl.watch(entrypoint, **kwargs)
@@ -1618,10 +1604,11 @@ class Compiler:
     @overload
     def on(self, signal: Literal["diagnostics"], callback: CompilerDiagnosticsCallback) -> None: ...
 
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def on(self, signal: str, callback: Callable[..., Any]) -> None:
+        """
+        Add a signal handler
+        """
+
         self._impl.on(signal, callback)
 
     @overload
@@ -1636,10 +1623,11 @@ class Compiler:
     @overload
     def off(self, signal: Literal["diagnostics"], callback: CompilerDiagnosticsCallback) -> None: ...
 
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
     def off(self, signal: str, callback: Callable[..., Any]) -> None:
+        """
+        Remove a signal handler
+        """
+
         self._impl.off(signal, callback)
 
 
@@ -1649,16 +1637,11 @@ PackageManagerInstallProgressCallback = Callable[
             "initializing",
             "preparing-dependencies",
             "resolving-package",
-            "using-lockfile-data",
-            "metadata-fetched",
             "fetching-resource",
             "package-already-installed",
             "downloading-package",
             "package-installed",
             "resolving-and-installing-all",
-            "awaiting-completion",
-            "dependencies-processed",
-            "finalizing-manifests",
             "complete",
         ],
         float,
@@ -1667,6 +1650,8 @@ PackageManagerInstallProgressCallback = Callable[
     None,
 ]
 
+PackageRole = Literal["runtime", "development", "optional", "peer"]
+
 
 class PackageManager:
     def __init__(self) -> None:
@@ -1701,31 +1686,23 @@ class PackageManager:
     def install(
         self,
         project_root: Optional[str] = None,
+        role: Optional[PackageRole] = None,
         specs: Optional[Sequence[str]] = None,
+        omits: Optional[Sequence[PackageRole]] = None,
     ) -> _frida.PackageInstallResult:
         kwargs: Dict[str, Any] = {
             "project_root": project_root,
+            "role": role,
             "specs": specs,
+            "omits": omits,
         }
         _filter_missing_kwargs(kwargs)
         return self._impl.install(**kwargs)
 
-    @overload
-    def on(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None: ...
-
-    @overload
-    def on(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def on(self, signal: str, callback: Callable[..., Any]) -> None:
+    def on(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None:
         self._impl.on(signal, callback)
 
-    @overload
-    def off(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None: ...
-
-    @overload
-    def off(self, signal: str, callback: Callable[..., Any]) -> None: ...
-
-    def off(self, signal: str, callback: Callable[..., Any]) -> None:
+    def off(self, signal: Literal["install-progress"], callback: PackageManagerInstallProgressCallback) -> None:
         self._impl.off(signal, callback)
 
 

subprojects/frida-core.wrap

@@ -1,6 +1,6 @@
 [wrap-git]
 url = https://github.com/frida/frida-core.git
-revision = 17.2.2
+revision = 17.9.7
 depth = 1
 
 [provide]