Como ler e editar arquivos plist
Última atualização:
Saber ler e editar um arquivo plist é trabalhar com o formato de configuração da Apple — os arquivos de chave-valor que movem o macOS e o iOS em silêncio. Cada app traz um Info.plist, cada tarefa agendada em segundo plano é um plist do launchd, cada perfil de provisionamento e cada perfil de dispositivo .mobileconfig é um plist por baixo. O formato em si é simples: dicionários, arrays, strings, números, booleanos, datas e dados binários, aninhados o quanto você quiser. O problema começa porque o mesmo formato é distribuído com dois disfarces — XML legível para humanos, e uma forma binária compacta que parece lixo num editor de texto — e porque um único tipo errado pode impedir silenciosamente que uma tarefa seja executada. Você pode colar qualquer plist no Plist Workbench e lê-lo, editá-lo, convertê-lo e validá-lo no seu navegador — nada é enviado — mas este artigo ensina você a ler os arquivos sozinho, para que a árvore nunca seja uma caixa-preta.
O que é um plist — e os quatro disfarces que ele usa
Uma lista de propriedades, ou plist, é a forma da Apple de guardar configuração estruturada: uma árvore de dicionários e arrays cujas folhas são strings, inteiros, números reais, booleanos, datas e blocos de dados binários. É a mesma ideia de um objeto JSON ou de um arquivo YAML, mas é anterior a ambos nas plataformas da Apple e está embutida no sistema operacional — o macOS e o iOS leem plists o tempo todo, sem nunca perguntar a você. Se você já se perguntou onde um app guarda seu bundle ID, sua versão ou as permissões que pede, a resposta é um plist, e ele esteve à vista o tempo todo.
O mesmo formato aparece em quatro lugares que parecem não ter relação até você conhecer o truque. Dentro de cada pacote de app, o Info.plist declara a identidade do app: seu bundle ID, versão, tipos de documento suportados e as permissões que solicita. Em ~/Library/LaunchAgents e /Library/LaunchDaemons, os arquivos de tarefas do launchd descrevem tarefas em segundo plano: o que executar, quando e em que condições. Um perfil de provisionamento .mobileprovision é um plist (envolvido numa assinatura CMS) que lista quais dispositivos e permissões um app pode usar. E um perfil de dispositivo .mobileconfig é um plist que descreve o Wi-Fi, a VPN, os certificados e as restrições a instalar num dispositivo. O mesmo formato, quatro disfarces — aprenda a ler um e você saberá ler os quatro.
Binário vs XML: a mágica bplist00, e por que editar um plist binário à mão o corrompe
Um plist tem duas serializações. A forma XML começa com <?xml e <plist version="1.0">, e pode ser lida em qualquer editor de texto: as chaves em tags <key>, os valores em <string>, <integer>, <true/>, <array> e <dict>. A forma binária é uma codificação compacta que começa com os oito bytes mágicos bplist00, seguidos de uma tabela de objetos, uma tabela de offsets e um trailer que registra onde cada coisa mora. Plists binários são menores e o sistema os carrega mais rápido, e é por isso que a maioria dos plists de um Mac de verdade é binária — e por isso abrir um deles num editor de texto mostra lixo.
Como saber qual você tem: olhe os primeiros bytes. bplist00 significa binário; <?xml ou <plist significa XML. E aqui está a regra que salva arquivos: nunca edite os bytes binários à mão. Um plist binário é uma teia de offsets — mude uma string para uma mais longa e todos os offsets depois dela ficam errados, o trailer deixa de bater com a tabela e o arquivo fica corrompido, mesmo que o texto que você mudou pareça certo. O caminho seguro é sempre o mesmo: converter de binário para XML, editar o XML, converter de volta para binário e reanalisar o resultado para provar que ele continua válido. Num Mac, isso é plutil -convert xml1 e plutil -convert binary1; no navegador, o Plist Workbench faz a mesma viagem de ida e volta por você.
Lendo uma tarefa do launchd à mão: Label, ProgramArguments, RunAtLoad, KeepAlive, StartCalendarInterval
Uma tarefa do launchd é um plist com um vocabulário pequeno, e você pode ler uma em menos de um minuto quando conhece as chaves. Label é o nome único da tarefa, convencionalmente um domínio reverso como com.example.backup — o launchd o usa para identificar a tarefa, e duas tarefas com o mesmo rótulo colidem. ProgramArguments é um array de strings: o programa a executar seguido de seus argumentos, de modo que ["/usr/local/bin/backup.sh"] executa esse script sem argumentos. RunAtLoad é um booleano: true significa executar a tarefa assim que ela for carregada. KeepAlive, também booleano, significa reiniciá-la sempre que ela terminar. Essas quatro chaves descrevem a maioria das tarefas que você vai encontrar.
A chave de agendamento é StartCalendarInterval, um dicionário de campos de calendário — Minute, Hour, Day, Weekday, Month — qualquer um dos quais você pode omitir, de modo que {Hour: 3, Minute: 30} significa todos os dias às 03:30. Sua prima mais simples, StartInterval, é um único inteiro: executar a cada N segundos. A amostra no bloco de código abaixo é uma tarefa completa e funcional nessa forma — Label, ProgramArguments, RunAtLoad, StartCalendarInterval — e vale a pena lê-la linha por linha, porque cada tarefa do launchd que você encontrar é uma variação dela: as mesmas chaves, valores diferentes, e um extra ocasional como WorkingDirectory ou StandardOutPath para indicar para onde vai a saída.
As chaves que quebram as coisas: erros de tipo, contêineres errados, números fora do intervalo
A maioria das tarefas do launchd quebradas não se quebra por erros de digitação — se quebra por tipos. O launchd espera que ProgramArguments seja um array de strings; entregue uma única string e a tarefa não carrega, com um erro que diz muito pouco. KeepAlive, RunAtLoad e Disabled precisam ser booleanos, não as strings "true" e "false" — uma string que soletra "true" não é true, e o launchd a tratará como erro de tipo. StartInterval precisa ser um inteiro positivo; zero ou número negativo não faz sentido e é rejeitado. Esses são os erros que um editor de texto nunca detecta, porque o XML está perfeitamente bem formado — só o significado está errado.
A segunda família de quebras são os números fora do seu intervalo. Em StartCalendarInterval, Minute precisa ser 0–59, Hour 0–23, Weekday 0–7, Day 1–31 e Month 1–12 — um Hour de 25 não significa "amanhã à 1h", significa que a tarefa nunca executa, e o launchd pode nem dizer por quê. A terceira família é o par que não deve aparecer junto: Program e ProgramArguments são duas formas de dizer a mesma coisa, e dar as duas é ambíguo — escolha uma, e prefira ProgramArguments, que é a forma que a Apple documenta. Um validador que verifica tipos, intervalos e esses conflitos detecta as três famílias antes que a tarefa chegue ao launchd, que é exatamente o que as verificações de launchd do workbench fazem.
Editando com segurança: backup, converter, editar, converter de volta, verificar
Editar um plist com segurança é um ritual de cinco passos, e a ordem importa. Primeiro, faça backup do arquivo original — copie-o para outro lugar antes de tocá-lo, porque uma tarefa do launchd ou um perfil de dispositivo não tem botão de desfazer. Segundo, se o arquivo for binário, converta-o para XML; nunca edite os bytes binários diretamente, pelas razões de offset acima. Terceiro, faça a edição no XML: mude um valor, renomeie uma chave, adicione um item ao array — e mantenha os tipos certos, uma string onde vai uma string, um array onde vai um array. Quarto, converta de volta para binário se o original era binário, para que o arquivo volte na forma que o sistema espera.
Quinto, e o passo mais ignorado: verifique reanalisando. Rode plutil -lint no resultado, ou cole-o no workbench e veja-o ser analisado sem erros — se o arquivo for reanalisado e os valores que voltaram forem os que você queria, a edição funcionou. Se ele não for analisado, você ainda tem o backup do passo um, e o arquivo no disco nunca foi tocado pelo editor: o workbench edita uma cópia em memória e só escreve um arquivo quando você exporta explicitamente. Essa última propriedade é todo o sentido de editar no navegador — o original fica intacto até você decidir que a nova versão é boa.
O que o Plist Workbench faz — e o que ele não faz
O workbench analisa as duas formas de plist — binário bplist00 e XML — numa árvore que você pode expandir, buscar por caminho (como StartCalendarInterval.Hour) e editar no lugar: mudar um escalar, renomear uma chave, adicionar ou remover chaves e itens de array, e mudar o tipo de um valor quando isso não for ambíguo. Cada exportação — plist XML, plist binário, JSON ou um CSV da tabela de caminhos achatada — reflete o modelo editado, não o arquivo original. Quando o plist parece uma tarefa do launchd, ele executa as verificações semânticas das seções anteriores: Label presente, exatamente um de Program e ProgramArguments, campos de calendário dentro do intervalo, booleanos que realmente são booleanos. Esse é todo o trabalho, e tudo acontece no seu navegador: o arquivo nunca sai do seu dispositivo.
O que ele não faz é igualmente importante. Ele não instala nada — não vai carregar sua tarefa no launchd, instalar um .mobileconfig num dispositivo ou provisionar um app; essas são ações do sistema, e uma página web não deveria executá-las. Ele não valida assinaturas de código nem permissões de provisionamento contra a Apple, de modo que um .mobileprovision editado pode ser analisado perfeitamente e ainda assim ser rejeitado pelo sistema porque sua assinatura não bate mais — analisar não é confiar. E ele não executa nada do plist: uma tarefa do launchd que aponta para um script é dado até o launchd executá-la, e o workbench a trata como dado. Para o equivalente no Android — o manifesto dentro de um APK — use o Analisador de APK; para o primo do launchd no Linux, as units do systemd, use o Auditor de units do systemd.
Teste você mesmo: uma tarefa do launchd que você pode ler, converter e verificar
# A minimal launchd job, as XML — the form you can read and edit safely
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.example.backup</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/backup.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartCalendarInterval</key>
<dict>
<key>Hour</key>
<integer>3</integer>
<key>Minute</key>
<integer>30</integer>
</dict>
</dict>
</plist>
# Convert between the two forms on a Mac — never edit the binary bytes:
$ plutil -convert xml1 job.plist # binary -> readable XML
$ plutil -convert binary1 job.plist # XML -> compact binary, for shipping
$ plutil -lint job.plist # re-parse to verify it is still valid