A primeira tela que um usuário vê

Quando você distribui um app macOS por conta própria, o usuário baixa um arquivo .dmg e dá um duplo clique nele. Nesse momento, uma única janela do Finder se abre. Esta janela é a primeira tela onde o usuário encontra seu app.

Uma janela .dmg bem feita geralmente tem esta aparência — uma imagem de guia preenche o fundo, o ícone do app fica à esquerda e um atalho para a pasta Applications fica à direita. O usuário conclui a instalação arrastando o ícone do app para Applications. Esse fluxo de “arrastar para instalar” é efetivamente a experiência de instalação padrão para apps macOS independentes.

Esta janela não aparece sozinha. Você precisa definir a imagem de fundo, o tamanho da janela e a posição e o tamanho de cada ícone por conta própria. Esta série cobre como projetar essa janela .dmg.

Esta série parte do pressuposto de que você já tem um .app que foi assinado, notarizado e grampeado (stapled) — em outras palavras, um app que está a um passo da distribuição. Esse processo foi coberto na série “Distribuindo um app macOS por conta própria”. Um .dmg é um artefato do canal de distribuição direta (Developer ID) e não tem nada a ver com o canal da Mac App Store.

O que esta série constrói

Ao longo de duas partes, você terá o seguinte:

• (Parte 1, este artigo) A ferramenta create-dmg + uma pasta de staging que contém apenas o .app + uma imagem de fundo preparada
• (Parte 2) Projetando as coordenadas da janela, ícones e drop link + alinhando a imagem de fundo com essas coordenadas + automação

Ao final da série, você deverá ter:

• Uma pasta de staging que isola e contém apenas o .app
• Uma imagem de fundo que segue a convenção @2x Retina e tem DPI normalizado
• Um comando create-dmg em que o tamanho da janela e as posições dos ícones são todos definidos por coordenadas
• Uma forma que pode ser reutilizada como está para cada lançamento

App de exemplo — FocusTimer

Como nas séries anteriores, usaremos um app macOS fictício, FocusTimer (um app de temporizador simples para gerenciar o tempo de foco), como exemplo. FocusTimer, os caminhos, os valores de coordenadas e assim por diante são todos exemplos. Na prática, adapte-os ao seu próprio app.

O que é um DMG?

Um DMG (.dmg) é um arquivo de imagem de disco (disk image) do macOS. Pense nele como um “disco virtual” que empacota toda uma estrutura de pasta e arquivo dentro de um único arquivo. Quando o usuário dá um duplo clique em um .dmg, o macOS o monta como um disco, e seu conteúdo se abre em uma janela do Finder.

Eis por que os DMGs são usados para distribuição de apps:

• Um app (.app) é na verdade uma pasta. É difícil colocar uma pasta diretamente na internet, mas envolvê-la em um DMG a transforma em um único arquivo.
• Você pode incluir um atalho para a pasta Applications dentro da janela do DMG, guiando o usuário a instalar com um único arrastar.
• Você pode projetar a aparência da janela — seu fundo, posições dos ícones e assim por diante — tornando a experiência de instalação mais limpa.

A ferramenta — create-dmg

Criar um DMG manualmente significa passar por várias etapas: criar uma imagem com hdiutil, montá-la, manipular a janela do Finder com AppleScript para posicionar os ícones e depois desmontá-la novamente. É tedioso e propenso a erros.

create-dmg é uma ferramenta de código aberto que agrupa todo esse processo em um único comando. Passe-lhe a imagem de fundo, o tamanho da janela e as coordenadas dos ícones como opções, e ela produz um .dmg finalizado para você.

Você já a instalou quando configurou as ferramentas de pré-requisito na Parte 1 da série “Distribuindo um app macOS por conta própria”. Se ainda não o fez, instale com o Homebrew:

brew install create-dmg

Há dois projetos chamados create-dmg. O usado neste artigo é a ferramenta de linha de comando instalada pelo Homebrew (create-dmg/create-dmg). Não a confunda com o projeto separado, que tem nomes de opções diferentes.

Passo 1 — Uma pasta de staging que contém apenas o .app

O DMG deve conter apenas um ícone de app, de forma limpa. Mas quando você compila e exporta seu app, a pasta resultante contém não apenas o .app, mas também arquivos de subproduto como DistributionSummary.plist e logs de empacotamento. Se você transformar essa pasta diretamente em um DMG, esses subprodutos também acabarão expostos na janela.

Então você copia apenas o .app para uma pasta vazia para isolá-lo e então usa essa pasta como material bruto para o DMG. Essa pasta de isolamento é comumente chamada de pasta de staging.

# Copie apenas o .app para uma pasta vazia para não misturar com subprodutos
DMG_STAGE="build/dmg-stage"
rm -rf "$DMG_STAGE"
mkdir -p "$DMG_STAGE"
cp -R "build/export/FocusTimer.app" "$DMG_STAGE/"

Agora build/dmg-stage/ contém apenas FocusTimer.app. Quando você construir o DMG, aponte o create-dmg para essa pasta, e a janela mostrará apenas o ícone do app, de forma limpa. (O atalho para a pasta Applications é gerado automaticamente via uma opção do create-dmg na Parte 2.)

Passo 2 — Preparando a imagem de fundo

O coração do design da janela DMG é a imagem de fundo. Este é o ponto onde as pessoas mais frequentemente ficam presas, então vamos passar por isso passo a passo.

Tamanho da tela — Por que 1200×800?

Na Parte 2, você definirá o tamanho da janela do DMG passando --window-size 600 400 para o create-dmg. Aqui, a unidade de 600 e 400 não é pixels, mas pontos (points). Pontos são a unidade de coordenada lógica que o macOS usa.

Em um display Retina, 1 ponto é desenhado como 2 pixels. Então, para preencher uma janela de 600×400 pontos completamente e nitidamente, a imagem de fundo deve ter o dobro desse tamanho — 1200×800 pixels. Esta é a convenção @2x (resolução dupla).

Para resumir — a janela tem 600×400 pontos, e a imagem de fundo tem 1200×800 pixels. Essa relação de 2× volta como um fator importante quando você configura coordenadas na Parte 2.

O que desenhar no fundo

Aqui vale abordar um equívoco comum. Não desenhe o ícone do app ou o ícone da pasta Applications na imagem de fundo. Esses ícones são colocados na janela como arquivos reais pelo create-dmg (Parte 2).

O que vai na imagem de fundo são apenas elementos de decoração e orientação:

• Uma seta apontando do ícone do app em direção à pasta Applications — o design mais comum para guiar os olhos e a mão do usuário a “arrastar nessa direção”.
• Se necessário, uma frase instrucional curta como “Arraste aqui”
• Uma cor de marca ou um padrão de fundo sutil

Em outras palavras, a imagem de fundo é “uma imagem que deixa vazios os locais onde os ícones ficarão e desenha apenas a linha guia que os conecta.” Você deixa os dois locais dos ícones — esquerdo e direito, cada um com 100 pontos = 200 pixels de tamanho (na Parte 2) — vazios e coloca a seta no espaço entre eles.

Uma armadilha importante — DPI

A armadilha em que as pessoas caem com mais frequência na imagem de fundo é o DPI (pixels por polegada).

Quando você exporta um PNG de um editor de imagem, o arquivo armazena não apenas a contagem de pixels (1200×800), mas também um valor de DPI. Quando o Finder desenha o fundo do DMG, ele olha para esse DPI para calcular de volta “quantos pontos essa imagem tem”. O cálculo é aproximadamente assim:

Tamanho em pontos = contagem de pixels ÷ (DPI ÷ 72)

• Se o DPI for 144: 1200 ÷ (144 ÷ 72) = 1200 ÷ 2 = 600 pontos. Preenche a janela (600pt) exatamente. ✅
• Mas alguns editores de imagem (ex.: Pixelmator Pro) gravam um valor de DPI arbitrário (ex.: 338) na exportação. Se o DPI for 338: 1200 ÷ (338 ÷ 72) ≈ 256 pontos. Isso é muito menor que a janela (600pt), então o fundo é desenhado encolhido no canto superior esquerdo da janela. ❌

A contagem de pixels é a mesma 1200×800 nos dois casos, mas o fundo quebra por causa de um valor de DPI. Da primeira vez que você se deparar com isso, a causa é genuinamente difícil de rastrear.

A solução é forçar o DPI do PNG exportado para um valor uniforme de 144. Uma linha com o comando sips, integrado ao macOS por padrão, faz isso:

sips -s dpiWidth 144 -s dpiHeight 144 dmg-background.png

Depois de executar essa linha, não importa qual DPI o editor gravou, ele é definido como 144, e 1200×800 pixels é interpretado como exatamente 600×400 pontos.

A conclusão — ① faça a imagem de fundo com 1200×800 pixels, e ② após exportar, normalize o DPI para 144 com sips. Siga essas duas regras e você evitará a armadilha de DPI.

Resumo da Parte 1

Se você acompanhou até aqui, agora tem:

• ✅ A ferramenta create-dmg instalada + entendimento do seu papel
• ✅ Uma pasta de staging que isola e contém apenas o .app (build/dmg-stage/)
• ✅ Uma imagem de fundo criada com 1200×800 pixels com o DPI normalizado para 144

Os materiais estão prontos. Mas você ainda não tem uma janela para exibir a imagem de fundo e posicionar os ícones. Com que tamanho abrir a janela, e onde colocar o ícone do app e o atalho para Applications — tudo isso é decidido pelas coordenadas que você passa para o create-dmg.

Na próxima parte, projetaremos essas coordenadas uma por uma, explicaremos como alinhar as coordenadas em pixels da imagem de fundo com as coordenadas em pontos da janela para que a seta na imagem de fundo fique exatamente entre os dois ícones, e mostraremos como automatizar esse processo para que possa ser reutilizado em cada lançamento.