Incrustar binarios externos

Es posible que necesitas incrustar binarios externos para añadir funcionalidad adicional a tu aplicación o evitar que los usuarios tengan que instalar dependencias adicionales (por ejemplo, Node.js o Python). A este binario lo llamamos Sidecar.

Los binarios son ejecutables escritos en cualquier lenguaje de programación. Casos de uso habituales son aplicaciones CLI de Python o servidores API empaquetados usando pyinstaller.

Para empaquetar los binarios que elijas, puedes añadir la propiedad externalBin al objeto bundle en tu tauri.conf.json. La configuración externalBin espera una lista de cadenas que apunten a los binarios, ya sea con rutas absolutas o relativas.

Aquí tienes un fragmento de configuración de Tauri para ilustrar la configuración de un sidecar:

src-tauri/tauri.conf.json

{
  "bundle": {
    "externalBin": [
      "/absolute/path/to/sidecar",
      "../relative/path/to/binary",
      "binaries/my-sidecar"
    ]
  }
}

Nota

Las rutas relativas son relativas al archivo tauri.conf.json que se encuentra en el directorio src-tauri. Así que binaries/my-sidecar representaría <PROJECT ROOT>/src-tauri/binaries/my-sidecar.

Para que el binario externo funcione en cada arquitectura soportada, debe existir un binario con el mismo nombre y un sufijo -$TARGET_TRIPLE en la ruta especificada. Por ejemplo, "externalBin": ["binaries/my-sidecar"] requiere un ejecutable src-tauri/binaries/my-sidecar-x86_64-unknown-linux-gnu en Linux o src-tauri/binaries/my-sidecar-aarch64-apple-darwin en macOS con Apple Silicon.

Puedes encontrar el sufijo -$TARGET_TRIPLE de tu plataforma actual ejecutando el siguiente comando:

rustc --print host-tuple

Esto imprime directamente el target triple de tu sistema (por ejemplo, x86_64-unknown-linux-gnu o aarch64-apple-darwin).

Nota

El indicador --print host-tuple se añadió en Rust 1.84.0. Si estás usando una versión anterior, tendrás que analizar la salida de rustc -Vv en su lugar:

# Unix (Linux/macOS)
rustc -Vv | grep host | cut -f2 -d' '

# Windows PowerShell
rustc -Vv | Select-String "host:" | ForEach-Object {$_.Line.split(" ")[1]}

Aquí tienes un script de Node.js para añadir el triple de destino a un binario:

import { execSync } from 'child_process';
import fs from 'fs';

const extension = process.platform === 'win32' ? '.exe' : '';

const targetTriple = execSync('rustc --print host-tuple').toString().trim();
if (!targetTriple) {
  console.error('Failed to determine platform target triple');
}
fs.renameSync(
  `src-tauri/binaries/sidecar${extension}`,
  `src-tauri/binaries/sidecar-${targetTriple}${extension}`
);

Ten en cuenta que este script no funcionará si compilas para una arquitectura diferente a la que se está ejecutando, así que solo úsalo como punto de partida para tus propios scripts de compilación.

Ejecutarlo desde Rust

Nota

Por favor, sigue primero la guía del plugin shell para configurar e inicializar el plugin correctamente. Sin que el plugin esté inicializado y configurado, el ejemplo no funcionará.

En el lado de Rust, importa el trait tauri_plugin_shell::ShellExt y llama a la función shell().sidecar() en el AppHandle:

use tauri_plugin_shell::ShellExt;
use tauri_plugin_shell::process::CommandEvent;
use tauri::Emitter;

let sidecar_command = app.shell().sidecar("my-sidecar").unwrap();
let (mut rx, mut child) = sidecar_command
  .spawn()
  .expect("Failed to spawn sidecar");

tauri::async_runtime::spawn(async move {
  // read events such as stdout
  while let Some(event) = rx.recv().await {
    if let CommandEvent::Stdout(line_bytes) = event {
      let line = String::from_utf8_lossy(&line_bytes);
      app
        .emit("message", Some(format!("'{}'", line)))
        .expect("failed to emit event");
      // write to stdin
      child.write("message from Rust\n".as_bytes()).unwrap();
    }
  }
});

Nota

La función sidecar() espera solo el nombre del archivo, NO la ruta completa configurada en el arreglo externalBin.

Dada la siguiente configuración:

src-tauri/tauri.conf.json

{
  "bundle": {
    "externalBin": ["binaries/app", "my-sidecar", "../scripts/sidecar"]
  }
}

La forma adecuada de ejecutar el sidecar es llamando a app.shell().sidecar(name) donde name es "app", "my-sidecar" o "sidecar" en lugar de "binaries/app", por ejemplo.

Puedes colocar este código dentro de un comando de Tauri para pasar fácilmente el AppHandle o puedes guardar una referencia al AppHandle en el script del constructor para acceder a él en cualquier otra parte de tu aplicación.

Ejecutarlo desde JavaScript

Al ejecutar el sidecar, Tauri requiere que le otorgues permiso para ejecutar el método execute o spawn en el proceso hijo. Para otorgar este permiso, ve al archivo <PROJECT ROOT>/src-tauri/capabilities/default.json y añade la sección siguiente al arreglo de permisos. No olvides nombrar tu sidecar según la ruta relativa mencionada anteriormente.

src-tauri/capabilities/default.json

{
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "name": "binaries/app",
          "sidecar": true
        }
      ]
    }
  ]
}

Nota

El identificador shell:allow-execute se usa porque el proceso hijo del sidecar se iniciará utilizando el método command.execute(). Para ejecutarlo con command.spawn(), debes cambiar el identificador a shell:allow-spawn o añadir otra entrada al arreglo con la misma estructura que la anterior, pero con el identificador establecido en shell:allow-spawn.

En el código de JavaScript, importa la clase Command del módulo @tauri-apps/plugin-shell y usa el método estático sidecar.

import { Command } from '@tauri-apps/plugin-shell';
const command = Command.sidecar('binaries/my-sidecar');
const output = await command.execute();

Nota

La cadena proporcionada a Command.sidecar debe coincidir con una de las cadenas definidas en el arreglo de configuración externalBin.

Pasar argumentos

Puedes pasar argumentos a comandos de Sidecar al igual que lo harías al ejecutar un Command normal.

Los argumentos pueden ser estáticos (por ejemplo, -o o serve) o dinámicos (por ejemplo, <file_path> o localhost:<PORT>). Un valor de true permitirá que se pase cualquier argumento al comando. false desactivará todos los argumentos. Si no se establece ni true ni false, defines los argumentos en el orden exacto en el que los llamarías. Los argumentos estáticos se definen tal cual, mientras que los argumentos dinámicos se pueden definir mediante una expresión regular.

Primero, define los argumentos que deben pasarse al comando sidecar en src-tauri/capabilities/default.json:

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/desktop-schema.json",
  "identifier": "default",
  "description": "Capability for the main window",
  "windows": ["main"],
  "permissions": [
    "core:default",
    {
      "identifier": "shell:allow-execute",
      "allow": [
        {
          "args": [
            "arg1",
            "-a",
            "--arg2",
            {
              "validator": "\\S+"
            }
          ],
          "name": "binaries/my-sidecar",
          "sidecar": true
        }
      ]
    }
  ]
}

Nota

Si estás migrando desde Tauri v1, el comando migrate en la CLI de Tauri v2 debería encargarse de esto por ti. Lee Migración automatizada para obtener más información.

Luego, para llamar al comando sidecar, simplemente pasa todos los argumentos como un arreglo.

En Rust:

use tauri_plugin_shell::ShellExt;
#[tauri::command]
async fn call_my_sidecar(app: tauri::AppHandle) {
  let sidecar_command = app
    .shell()
    .sidecar("my-sidecar")
    .unwrap()
    .args(["arg1", "-a", "--arg2", "any-string-that-matches-the-validator"]);
  let (mut _rx, mut _child) = sidecar_command.spawn().unwrap();
}

En JavaScript:

import { Command } from '@tauri-apps/plugin-shell';
// notice that the args array matches EXACTLY what is specified in `capabilities/default.json`.
const command = Command.sidecar('binaries/my-sidecar', [
  'arg1',
  '-a',
  '--arg2',
  'any-string-that-matches-the-validator',
]);
const output = await command.execute();