Interpretadores

Por padrão, o Invowk™ executa scripts usando um shell. Mas você pode usar outros interpretadores como Python, Ruby, Node.js ou qualquer executável que possa rodar scripts.

Auto-Detecção a partir do Shebang

Quando um script começa com um shebang (#!), o Invowk automaticamente usa esse interpretador:

{
    name: "analyze"
    implementations: [{
        script: """
            #!/usr/bin/env python3
            import sys
            import json
            
            data = {"status": "ok", "python": sys.version}
            print(json.dumps(data, indent=2))
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Padrões comuns de shebang:

Shebang	Interpretador
#!/usr/bin/env python3	Python 3 (portável)
#!/usr/bin/env node	Node.js
#!/usr/bin/env ruby	Ruby
#!/usr/bin/env perl	Perl
#!/bin/bash	Bash (caminho direto)

Interpretador Explícito

Especifique um interpretador diretamente na configuração do runtime:

{
    name: "script"
    implementations: [{
        script: """
            import sys
            print(f"Python {sys.version_info.major}.{sys.version_info.minor}")
            """
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "native"
            interpreter: "python3"  // Explicit
        }]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

O interpretador explícito tem precedência sobre a detecção de shebang.

Interpretador com Argumentos

Passe argumentos para o interpretador:

{
    name: "unbuffered"
    implementations: [{
        script: """
            import time
            for i in range(5):
                print(f"Count: {i}")
                time.sleep(1)
            """
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "native"
            interpreter: "python3 -u"  // Unbuffered output
        }]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Mais exemplos:

// Perl with warnings
interpreter: "perl -w"

// Ruby with debug mode
interpreter: "ruby -d"

// Node with specific options
interpreter: "node --max-old-space-size=4096"

Interpretadores em Containers

Interpretadores funcionam em containers também:

{
    name: "analyze"
    implementations: [{
        script: """
            #!/usr/bin/env python3
            import os
            print(f"Running in container at {os.getcwd()}")
            """
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "container"
            image: "python:3-slim"
        }]
        platforms: [{name: "linux"}]
    }]
}

Ou com interpretador explícito:

{
    name: "script"
    implementations: [{
        script: """
            console.log('Hello from Node in container!')
            console.log('Node version:', process.version)
            """
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "container"
            image: "node:20-slim"
            interpreter: "node"
        }]
        platforms: [{name: "linux"}]
    }]
}

Acessando Argumentos

Argumentos funcionam da mesma forma com qualquer interpretador:

{
    name: "greet"
    args: [{name: "name", description: "Name to greet", default_value: "World"}]
    implementations: [{
        script: """
            #!/usr/bin/env python3
            import sys
            import os
            
            # Via command line args
            name = sys.argv[1] if len(sys.argv) > 1 else "World"
            print(f"Hello, {name}!")
            
            # Or via environment variable
            name = os.environ.get("INVOWK_ARG_NAME", "World")
            print(f"Hello again, {name}!")
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Interpretadores Suportados

Qualquer executável no PATH pode ser usado:

• Python: python3, python
• JavaScript: node, deno, bun
• Ruby: ruby
• Perl: perl
• PHP: php
• Lua: lua
• R: Rscript
• Shell: bash, sh, zsh, fish
• Personalizado: Qualquer executável

Limitação do Runtime Virtual

O campo interpreter não é suportado com o runtime virtual:

// This will NOT work!
// CUE schema validation error: "interpreter" is not allowed on virtual runtime.
// #RuntimeConfigVirtual is a closed struct that only accepts base fields.
{
    name: "bad"
    implementations: [{
        script: "print('hello')"
        runtimes: [{
        platforms: [{name: "linux"}, {name: "macos"}]
            name: "virtual"
            interpreter: "python3"  // CUE validation error: field not allowed
        }]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

O runtime virtual usa o interpretador mvdan/sh embutido e não pode executar Python, Ruby ou outros interpretadores. Use runtime native ou container em vez disso.

Comportamento de Fallback

Quando não há shebang e nenhum interpretador explícito:

• Runtime native: Usa o shell padrão do sistema
• Runtime container: Usa /bin/sh -c

Melhores Práticas

1. Use shebang para portabilidade: Scripts funcionam standalone também
2. Use /usr/bin/env: Mais portável que caminhos diretos
3. Interpretador explícito para scripts sem shebang: Quando você não quer uma linha de shebang
4. Combine imagem do container: Garanta que o interpretador existe na imagem

Próximos Passos

• Diretório de Trabalho - Controlar local de execução
• Específico de Plataforma - Implementações por plataforma