Logo Cordova

Passo-a-passo para usar o Apache Cordova (PhoneGap) com Android SDK no Windows

(Atenção: este post está desatualizado . A versão atual pode ser encontrada aqui.)

Essa instalação me cansa só de pensar. Ela não é só demorada, é muito mal explicada no site do Cordova, sobretudo o passo da instalação do Apache Ant. Cada etapa depende da anterior pra funcionar corretamente: sem o NodeJS o Cordova não pode ser instalado, sem o Android SDK o Cordova não cria projetos Android, sem o Ant o Cordova não cria nada que precise de Java, e sem o Java nenhum desses funciona.

Instalação do Java e Java SDK

Versão do Java usada neste tutorial: 7 Update 55

  1. (opcional) Desinstala o Java e Java SDK, se já estiver na máquina.
  2. Faz download do pacote com Java e Java SDK em Ninite.com.
  3. Instala pacote do Ninite, até o final.
  4. Cria a variável de ambiente: JAVA_HOME=pasta do SDK, sempre sem terminar com / ou \ (no meu é C:\Program Files (x86)\Java\jdk1.7.0_55).
  5. Adiciona ao PATH: %JAVA_HOME%\bin .
  6. Eu por via das dúvidas adicionei também ao PATH a pasta bin do Java RE (C:\Program Files (x86)\Java\jre7\bin), mas talvez esse passo seja desnecessário.
  7. Por via das dúvidas daria pra reiniciar agora, mas acho que é desnecessário.

Instalação do Android SDK

(para poder criar projetos Android com ou sem o Cordova)

Versão do Android SDK usada neste tutorial: 20140321

  1. Download do SDK/Android Developer Tools: http://developer.android.com/sdk/index.html.
  2. Descompacta e escolhe onde o pacote vai ficar. Eu deixo em c:\Android, dentro ficam as pastas eclipse e sdk.
  3. (opcional) Cria atalhos para fácil acesso ao eclipse.exe e Android SDK.exe. O Android SDK está na raiz da pasta do Android Developer Tools e o eclipse.exe está na pasta eclipse. No Windows 8 isso pode ser feito entrando na pasta do Android Developer Tools e clicando com botão direito em cada um deles e selecionando “Fixar na Tela Inicial”, assim o atalho vai aparecer na Tela Inicial imediatamente e pode ser copiado para a área de trabalho ou outros locais.
  4. Abre o Eclipse, deixa rodar a primeira vez, escolhe uma pasta onde ficará o Workspace.
  5. Abre o SDK Manager, já pode mandar atualizar e baixar coisas que achar necessário (imagens do Intel x86 Atom system image, Intel x86 Emulator Accelerator recomendados).
  6. Cria a variável de ambiente: ANDROID_HOME=pasta do SDK, sem aspas e sem terminar com / ou \ (no meu é c:\Android\sdk).
  7. Adiciona ao PATH: %ANDROID_HOME%\tools e %ANDROID_HOME%\platform_tools .
  8. Por via das dúvidas daria pra reiniciar agora, mas acho que é desnecessário.

Instalação do Apache Ant

Versão do Ant usada neste tutorial: 1.9.4

Este é um passo importante que é mal documentado tanto no site do Cordova, do NodeJS e do próprio Ant. Não é difícil, mas é obrigatório e não está escrito nos tutoriais básicos de “como criar seu primeiro app com Cordova”. Vamos lá:

  1. Vai em http://ant.apache.org/bindownload.cgi e faz o download do Ant estável mais recente (.zip archive).
  2. Descompacta para o local que julgar conveniente (eu uso C:\Program Files\Ant).
  3. Cria a variável de ambiente: ANT_HOME=pasta do Ant (ex.: C:\Program Files\Ant).
  4. Adiciona ao PATH: %ANT_HOME%\bin .
  5. Agora convém reiniciar o computador e testar o Ant, abrindo uma janela de prompt de comando e executando o comando “ant”. Tem que retornar o seguinte:
    Buildfile: build.xml does not exist!
    Build failed

    É uma mensagem de erro normal que significa que o Ant foi reconhecido e tentou construir um programa Java e não conseguiu, porque não existe nenhum na pasta que você executou o comando. Se aparecer qualquer mensagem de erro ALÉM desta, algo deu errado, provavelmente o Ant não está localizando seu JAVA_HOME (nesse caso revise os passos de instalação do Java e Java SDK, os passos das variáveis de ambiente são obrigatórios).


Instalação do Cordova/PhoneGap

Versão do NodeJS usada neste tutorial: 0.10.28

Versão do Cordova usada neste tutorial: 3.5.0-0.2.4

  1. Vai em NodeJS.org, faz o download do NodeJS e instala no computador. Deixa todas as opções habilitadas, inclusive de adicionar o Path.
  2. Reinicia o computador.
  3. Abre o NodeJS command prompt recém instalado e insere o comando (necessário conexão com a internet):
    npm install -g cordova
  4. Espera até terminar de baixar e instalar todos os pacotes.

(opcional) Criação de um AVD (Android Virtual Device)

Para a testar um aplicativo Android criado pelo Cordova, há duas maneiras: instalando o aplicativo em um aparelho Android ou usando o emulador Android. Para usar o emulador você deve criar um AVD. Criar um AVD é muito fácil e rápido, mas se possível, recomendo criar um AVD que ao invés de tentar emular o processador ARM, usa arquitetura Intel x86 para rodar muito mais rápido no PC — é um pouco mais complicado mas vou ensinar como.

Criação de um AVD ARM

  1. Abre o SDK Manager
  2. No menu “Tools”, clica em Manage AVDs
  3. Deve abrir uma tela com a lista de AVDs criados, e ela deve estar vazia. Se já existir algum, você pode usar este que já foi criado anteriormente (nenhuma ação é necessária), ou criar um novo.
  4. Para criar um novo, clica em “New…”.
  5. Preenche o formulário:
    • AVD Name: qualquer coisa, desde que só use letras, números e símbolos simples como hífen e underline
    • Device: selecione o aparelho que deseja emular. Mais pra baixo na lista há várias configurações genéricas de aparelhos comuns. A diferença entre os aparelhos são especificações como tamanho da tela, memória RAM, etc. Se não conhecer nenhum, seleciona qualquer um.
    • Target: seleciona a versão do Android que prefere usar.
    • CPU/ABI: ARM
    • Keyboard: marcar se não estiver marcado
    • Skin: seleciona “Skin with dynamic hardware controls” ou outro que preferir
    • Front Camera e Back Camera: pode deixar sem nada (“None”), “Emulated” ou escolher uma webcam do computador. Isso nem sempre funciona, se der problema na emulação deixa “None”.
    • Memory Options (RAM): o recomendável é usar 768, mas se a emulação não funcionar, testa valores menores.
    • Memory Options (VM Heap): o valor provavelmente foi definido pelo Device escolhido, recomendável não alterar.
    • Internal storage: 200 MiB ou o valor que preferir.
    • SD Card: vazio ou o valor que preferir.
    • Emulation Options:
      • desmarca “Snapshot”
      • se estiver em uma máquina potente, pode marcar “Use Host GPU”
      • se a emulação não funcionar, desmarca “Use Host GPU”
  6. Dá OK e o AVD será criado e já pode ser usado.

(recomendado) Criação de um AVD x86

Observação: nem todo computador pode emular um Atom x86, isso depende do processador do seu computador. A maioria dos processadores modernos (i3-i7) pode emular o Atom sem problemas.

  1. Abre o SDK Manager
  2. Em Packages, nota o pacote Android mais recente (ex.: “Android 4.4.2 (API 19)”), abaixo dele deve aparecer instalado (“Installed”) o pacote “SDK Platform” (obrigatório para usar essa versão do Android no emulador) e o pacote Intel x86 Atom System Image (para essa versão do Android funcionar em um AVD x86).
  3. Ainda em Packages, lááá embaixo tem um pacote chamado Intel x86 Emulator Accelerator (HAXM installer), que também precisa estar instalado.
    • Se qualquer um destes pacotes mencionados não estiver instalado, marca os pacotes que estão faltando e clica no botão Install xx packages, onde “xx” é o número de pacotes sendo instalados ou atualizados.
    • Vai aparecer uma janela com a lista dos pacotes sendo instalados à esquerda, e a opção de aceitar a licença daqueles pacotes à direita. Seleciona todos os pacotes que tiverem um “x” vermelho e clica em “Accept license”.
    • Feito isso, clica em “Install”. É feito download dos pacotes e isso pode levar um tempo.
  4. O HAXM deve ser instalado manualmente, fora do SDK Manager. Depois de feito o download, entra na pasta do Android SDK, e dentro dela em extras > intel > Hardware_Accelerated_Execution_Manager. Roda o programa de instalação (intelhaxm.exe).
    • Se esse passo não funciona, ou o processador não é compatível com o HAXM, ou é compatível e tem alguma configuração errada. No meu caso o instalador acusou o erro e eu busquei a solução no Google (a virtualização estava desligada no meu PC), em outra máquina não precisei fazer nada, funcionou direto. Boa sorte.
  5. Com os pacotes necessários e o HAXM já instalados, de volta ao SDK Manager, no menu “Tools”, clica em Manage AVDs
  6. Clica em “New…”.
  7. Preenche o formulário:
    • AVD Name: qualquer coisa, desde que só use letras, números e símbolos simples como hífen e underline
    • Device: seleciona o aparelho que deseja emular. Mais pra baixo na lista há várias configurações genéricas de aparelhos comuns. A diferença entre os aparelhos são especificações como tamanho da tela, memória RAM, etc. Se não conhecer nenhum, seleciona qualquer um.
    • Target: seleciona a versão do Android que prefere usar.
    • CPU/ABI: Intel Atom (x86). Se essa opção não estiver disponível, é porque o pacote Intel x86 Atom System Image daquela versão específica do Android não foi instalado (passo 2).
    • Keyboard: marca se não estiver marcado.
    • Skin: seleciona “Skin with dynamic hardware controls” ou outro que preferir.
    • Front Camera e Back Camera: pode deixar sem nada (“None”), “Emulated” ou escolher uma webcam do computador. Isso nem sempre funciona, se der problema na emulação deixa “None”.
    • Memory Options (RAM): o recomendável é usar 768, mas se a emulação não funcionar, testa valores menores.
    • Memory Options (VM Heap): o valor provavelmente foi definido pelo Device escolhido, recomendável não alterar.
    • Internal storage: 200 MiB ou o valor que preferir.
    • SD Card: vazio ou o valor que preferir.
    • Emulation Options: desmarca “Snapshot” e desmarca “Use Host GPU”.
  8. Dá OK e o AVD será criado e já pode ser usado.

Criação e execução de um programa Hello World

Abre o Node.js command prompt e digita os seguintes comandos:

cordova create hello com.exemplo.helloworld HelloWorld
Este comando cria um projeto na pasta hello, com identificador em estilo domínio reverso com.exemplo.helloworld, de um aplicativo chamado HelloWorld. A pasta hello não deve existir antes de o comando ser executado, o Cordova vai criar a pasta e adicionar todos os arquivos do projeto. O aplicativo criado por enquanto faz só o mais básico: testa se o aparelho está pronto para rodar o aplicativo e exibe uma mensagem na tela. Mas ele não pode rodar até que sejam adicionadas as plataformas (abaixo).

cd hello
Entra na pasta hello.

cordova platform add android
Adiciona a plataforma Android a este projeto, ou em outras palavras, adiciona os arquivos para que o projeto funcione no Android. Lembre que você tem que estar dentro da pasta raiz do projeto (hello).

Para executar o programa, você tem duas opções de comandos principais:

  • cordova emulate android
    Roda o programa em uma janela de emulador Android, se houver um AVD criado anteriormente. Lembre que você tem que estar dentro da pasta raiz do projeto (hello). Isso pode levar alguns minutos.

ou

  • cordova run android
    Instala e roda o programa em um dispositivo Android conectado ao computador por USB. Lembre que você tem que estar dentro da pasta raiz do projeto (hello). Para isso funcionar, a depuração USB tem que estar habilitada no aparelho (normalmente em “Opções de desenvolvedor”). Se não funcionar, o Cordova tentará executar o app em um AVD criado anteriormente pelo emulador.

    • Quando isso não funciona, normalmente é porque o aparelho não está sendo reconhecido pelo Android Debug Brigde. Executa o comando adb devices. Deve aparecer algo como:
      List of devices attached
      SDFGKSDHGLSJH HTC ONE

      Se não aparece nenhum nome na lista, é porque o aparelho não foi reconhecido. Isso pode acontecer por muitas razões, mas recomendo instalar os drivers USB do aparelho no PC e procurar mais informações sobre “adb devices xxx” no Google, sendo xxx o modelo do seu aparelho. Boa sorte.

 

Update: Adicionando plugins ao programa

Abre o Node.js command prompt, navega até a pasta do raiz do projeto (ex.: hello). Para adicionar um plugin do Cordova ao programa, o comando é:

cordova plugin add <pacote>

… onde <pacote> é o nome de um pacote de plugin. Uma grande lista de plugins pode ser encontrada aqui. Os mais básicos estão aqui. Por exemplo, para trabalhar com o sistema de arquivos do aparelho, é necessário instalar o plugin “File”, com o seguinte comando:

cordova plugin add org.apache.cordova.file

Pra remover o mesmo plugin, troca “add” por “rm”.

cordova plugin rm org.apache.cordova.file


Se você curte meus tutoriais e se estiver a fim, pode me pagar uma cerveja. Escolha a que você prefere doar clicando abaixo (é pelo Paypal, mas não precisa conta para doar). Juro solenemente usar toda a receita de doações em cerveja apenas. Obrigado! 😉

(R$ 3,50) (R$ 7) (R$ 19)

3 thoughts on “Passo-a-passo para usar o Apache Cordova (PhoneGap) com Android SDK no Windows”

  1. Obrigado pelo tutorial, é difícil encontrar material de qualidade sobre o Phonegap, sem ele eu não conseguiria usar o Intel Atom e detectar um problema que ocorre com muitas pessoas com o ANT e como resolve-lo. Caso queira acrescentar, quando digitava ant no prompt ele acusava o erro: Unable to locate tools.jar.
    Expected to find it in C:\Program Files\Java\jre6\lib\tools.jar
    Por algum motivo ele procura tools.jar na pasta jre ao invés da jdk, mesmo com o PATH configurado corretamente. A solução que encontrei foi copiar tools.jar da pasta lib em jdk para o local em que ele espera encontrar, lib em jre.

    1. Oi Gustavo. Isso é muito estranho. Gostaria de poder reproduzir o erro, mas a verdade é que a cada versão do Android SDK percebo bugs e dificuldades diferentes, é praticamente impossível cobrir todos. De qualquer modo está feito o registro, obrigado pela informação.

  2. Cara valeu minha aplicação não estava rodando sendo que estava tudo certo e não encontrava o pacote java. Realizei a instalação e criação da variável ANT e funcionou. Obrigado, realmente não havia encontrado nenhum outro tutorial que informava esse processo.

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *