# Instalação do JAVA

<p class="callout warning">O Ancestris é compatível com as versões Java indicadas na página de [compatibilidade das versões](https://docs.ancestris.org/books/manual-do-utilizador/page/compatibilidade-das-versoes "Compatibilidade das versões").</p>

<p class="callout info">**Se o Ancestris não iniciar**, ou mostrar o ecrã inicial e parar, geralmente é um problema com a instalação do Java. Ou o Java <span style="text-decoration: underline;">não está instalado</span>, o <span style="text-decoration: underline;">Ancestris não o encontra</span>, <span style="text-decoration: underline;">encontra uma versão incompatível </span>ou <span style="text-decoration: underline;">encontra uma versão corrompida</span>.</p>

<p class="callout success">As secções seguintes mostram uma verificação passo-a-passo para garantir que o Ancestris usa uma versão Java 8 válida.</p>

## Princípio geral

- **O Ancestris funciona com as versões Java indicadas ao cimo da página**. 
    - O Ancestris é compilado na versão 8 para maior compatibilidade com o maior número de utilizadores.
    - Foi testado e funciona em versões LTS (Long Term Support).
    - Não testamos as versões Short Term, que se tornam rapidamente obsoletas e não podem ser transferidas após 18 meses, mas os utilizadores disseram-nos que o Ancestris também funciona em versões intermédias.
    - O Ancestris é compilado com uma versão de longo termo, para melhor compatibilidade com o maior número de utilizadores.
- Se uma versão funcional de Java estiver disponível no seu sistema, **o Ancestris encontrá-la-á sem ter de configurar nada**.
- Caso contrário, pode [instalar o Java](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-install-java "Instalar o Java") de qualquer fornecedor. Os nossos utilizadores sentem-se mais confortáveis com o [Adoptium](https://adoptium.net/ "Adoptium").
- Para saber se o Java está instalado no seu sistema, [siga estas instruções](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-identify-which-java- "Siga estas instruções").
- Se o Ancestris não iniciar quando o Java estiver instalado, consulte a secção [Resolução de problemas](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-d%C3%A9pannage).
- Podem estar instaladas várias versões de Java no seu sistema. Para indicar ao Ancestris qual delas deve ser utilizada, é necessário:
    
    
    - actualizar o ficheiro de configuração do Ancestris, [seguindo estas instruções](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-identify-which-java--0 "Siga estas instruções");
    - mudar a versão pré-definida do Java, [seguindo estas instruções](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-la-proc%C3%A9dure-d%C3%A9pend- "Siga estas instruções").

- 

## Instalação do Java

<p class="callout info">Uma forma simples de recuperar uma versão do Java, é transferi-la a partir de [Adoptium.net](https://adoptium.net/releases.html "Versions officielles de Java depuis Adoptium.net")  
- em macOS e Windows, o Adoptum disponibiliza pacotes de instalação que basta executar;  
- em Linux, pode ser mais simples realizar a instalação através da linha de comandos, por exemplo, no Ubuntu, seria "sudo apt install openjdk-21-jdk", se se pretender instalar a versão 21.</p>

Se não tiver o Java instalado, ou se pretender obter a versão mais recente ou uma versão específica do Java, basta transferi-lo a partir do sítio acima referido.

<p class="callout success">Se utiliza o Windows, durante a instalação do Java com o Adoptium, marque a caixa de instalação das chaves de registo Javasoft.  
[![pt-adoptium-install.png](https://docs.ancestris.org/uploads/images/gallery/2025-11/scaled-1680-/pt-adoptium-install.png)](https://docs.ancestris.org/uploads/images/gallery/2025-11/pt-adoptium-install.png)  
Isto permitirá aos programas o reconhecimento da instalação do Java.</p>

<p class="callout success">Se utiliza **Linux**, como o Adoptium já não faz pacotes, uma maneira simples é digitar o seguinte comando num terminal:   
<span data-darkreader-inline-bgcolor="" style="background-color: rgb(206, 212, 217); --darkreader-inline-bgcolor: var(--darkreader-background-000000, #000000);">sudo apt install openjdk-17-jdk  
</span>Subsitua o n.º 17 pelo número da versão que deseja instalar.</p>

## Saber se o Java está instalado

Se não souber se o Java está instalado ou qual a versão instalada, abra directamente um terminal de linha de comandos e insira:

```
java -version
```

- **Se vir uma mensagem de erro** no terminal, significa que o Java não está instalado no seu sistema. O Ancestris não pode ser executado. [Siga a secção Instalar](#bkmrk-install-java "Instalar o Java") abaixo para instalar o Java e depois inicie o Ancestris.
- **Se vir algo como o exemplo seguinte**, significa que tem a versão correcta instalada e pré-definida.

```
java version "1.8.0_251"
Java(TM) SE Runtime Environment (build 1.8.0_251-b08)
Java HotSpot(TM) 64-Bit Server VM (build 25.251-b08, mixed mode)
```

De acordo com o exemplo acima, podemos ver que a versão Java instalada e pré-definida é a versão 1.8, também conhecida como versão 8.

<p class="callout success">Se vir uma versão Java como no exemplo acima e está satisfeito com essa versão, pode ignorar o resto desta página.</p>

## Resolução de problemas

Se o Ancestris não iniciar, é porque <span style="text-decoration: underline;">não encontra o Java</span> ou <span style="text-decoration: underline;">encontra uma versão incompatível ou corrompida</span>.


Quer esteja instalada apenas uma versão do Java no seu sistema ou várias, terá de [verificar e possivelmente actualizar o ficheiro de configuração](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-identify-which-java--0 "Verifique o ficheiro de configuração") para indicar ao Ancestris onde encontrar o Java.

Em vez de modificar o ficheiro de configuração da Ancestris, e se estiverem disponíveis várias versões de Java no seu sistema, uma alternativa é [modificar a versão predefinida do Java](https://docs.ancestris.org/books/manual-do-utilizador/page/instala%C3%A7%C3%A3o-do-java#bkmrk-la-proc%C3%A9dure-d%C3%A9pend- "Modificar a versão predefinida do Java").

- A versão pré-definida do Java é a que aparece quando se escreve ```
    java -version
    ```
    
     como indicado na secção acima. Esta é a que a Ancestris utilizará se o ficheiro de configuração não existir ou não indicar onde encontrar o Java.

##### Em caso de dúvida, inicie o Ancestris manualmente a partir duma janela de terminal e envie-nos o texto que aparece no ecrã.

Independentemente do sistema operativo que estiver a utilizar, abra uma janela de terminal e:

- vá à pasta da aplicação `ancestris/bin;`
- Inicie o Ancestris manualmente;
- digitando `./ancestris` em macOS ou Linux;
- digitando `ancestris.exe` ou `ancestris64.exe` em Windows;
- a janela do terminal mostrará o que ele faz;
- envie-nos este ecrã.

## Actualizar o ficheiro de configuração do Ancestris

<p class="callout info">Não precisa de se preocupar com o que está detalhado abaixo a não ser que o Java não esteja instalado ou que o Ancestris não inicie.</p>

É necessário actualizar o [ficheiro de configuração do Ancestris](https://docs.ancestris.org/books/manual-do-utilizador/page/ficheiros-de-programa-e-ficheiros-de-configura%C3%A7%C3%A3o-do-utilizador "Ficheiros de programa e ficheiros de configuração do utilizador") para lhe indicar Ancestris onde encontrar Java, se o Ancestris não o conseguir encontrar por si próprio.

O princípio é o seguinte:

- se houver um ficheiro de configuração que inclua um parâmetro **jdkhome** indicando onde encontrar o Java, o Ancestris utilizará a versão java correspondente;
- caso contrário, o Ancestris utilizará a versão pré-definida do Java indicada na secção acima.

<p class="callout danger">**O Ancestris utiliza dois ficheiros de configuração, ambos chamados ancestris.conf**  
1. O primeiro é o ficheiro de <span style="text-decoration: underline;">configuração da aplicação</span>, que faz parte da pasta Aplicação e é criado quando o Ancestris é instalado.   
2. O outro é o ficheiro de <span style="text-decoration: underline;">configuração do utilizador</span>, que faz parte da pasta do utilizador e é criado quando modifica certas preferências ao utilizar o Ancestris.  
**O ficheiro de configuração do utilizador precede o ficheiro de configuração da aplicação.**  
  
O ficheiro de configuração a verificar e actualizar é, portanto, o ficheiro de configuração do utilizador, se existir, e o ficheiro de configuração da aplicação, se não existir.  
- Se estiver a instalar o Ancestris, terá provavelmente de actualizar o ficheiro de configuração da aplicação.  
- Se já utilizou o Ancestris e pretende alterar a versão do Java, terá provavelmente de actualizar o ficheiro de configuração do utilizador.   
</p>

Cliquez ici pour savoir où trouver le fichier de configuration en fonction de votre système.

### O caminho de acesso ao Java no ficheiro de configuração

Por isso, abra o ficheiro de configuração com um editor de texto normal.

**1. Localize a linha que define `default_options`**

Esta linha tem o seguinte aspecto:

`default_options="--branding ancestris -J-Xms96m -J-Xmx1g --laf javax.swing.plaf.nimbus.NimbusLookAndFeel"`

Se uma das opções nesta linha incluir `--jdkhome="/caminho/para/java`, assegure-se de que o caminho indicado nesta definição é o da versão Java que deseja utilizar.

Senão, procure por jdkhome noutro lado.

**2. Encontre a linha que define `jdkhome`**

Se existir, deve-se parecer com`jdkhome="/caminho/para/java"`. Assegure-se de que o caminho indicado nesta definição é o da versão Java que deseja utilizar.

Se a linha começa por "#", sinal de uma linha de comentário, o Ancestris ignorá-la-á e, por consequência, nnão terá em conta o parâmetro jdkhome indicado.

Se o Ancestris não iniciar, pode acontecer que o nome da pasta indicada por jdkhome esteja mal escrito ou que aponte para uma versão incorrecta do Java.

Qualquer que seja o seu sistema operativo, se a versão de Java a utilizar para o Ancestris for diferente da que está activada por defeito no seu sistema, é necessário modificar a linha jdkhome da seguinte forma:

```
jdkhome="/caminho/para/jdk"
```

### Caso do macOS

Para macOS, se, por exemplo, Java 18 e Java 17 estejam instalados no seu Mac e deseje forçar a utilização da versão Java 17 para o Ancestris, a manipulação completa será a seguinte:

- **Modificar o ficheiro de configuração do utilizador do Ancestris, se existir:**
    
    
    - O ficheiro é`/Users/<utilizador>/Library/Application Support/ancestris/<versão ou trunk>/etc/ancestris.conf`.
    - Substitua &lt;utilizador&gt; pelo nome do utilizador Mac.
    - Substitua &lt;versão ou trunk&gt; pelo número da bersão do Ancestris que utiliza: a versão estável actual, ou a versão quotidiana, chamada "trunk".
    - Para ver a pasta Library no Finder, deve premir Command+J. Está oculta por defeito.
- <div>**Se o ficheiro de configuração do utilizador não existir**, porque ainda não utilizou o Ancestris, por exemplo, edite o ficheiro de configuração da aplicação  
    `/Applications/Ancestris.app/Contents/Resources/ancestris/etc/ancestris.conf`</div>
- <div>**Encontre a linha** `#jdkhome="/caminho/para/java"` e suprima o carácter # do início da linha, para que o Ancestris a tenha em conta.</div>
- <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">Substitua-a por</span><span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">,</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">assumindo</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">que</span> T<span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">émurin</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">17</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">é</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">a</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">versão</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">de</span> J<span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">ava</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">a</span> <span class="--l --r hover:bg-blue-100 hover:dark:bg-blue-600">forçar:</span>

```
jdkhome="/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/Home"
```

<div id="bkmrk--6"></div>- Grave o ficheiro ancestris.conf assim modificado e verifique a gravação.
- Reinicie o Ancestris.

### Caso do Windows e do Linux

Para Windows ou Linux, por exemplo, se o executável Java for /usr/java/jdk1.8.0\_291-amd64/bin/java, deverá indicar:

```
jdkhome="/usr/java/jdk1.8.0_291-amd64/"
```

Nota: deve excluir /bin/java da descrição do caminho.

## Pré-definir a versão Java

- -
- [Para MacOS](#bkmrk-set-the-default-java "Escolher a versão Java para MacOS")
- [Para Windows](#bkmrk-swaping-java-version-0 "Escolher a versão Java para Windows")
- [Para Linux](#bkmrk-swaping-java-version-1 "Escolher a versão Java para Linux")

### Pré-definir a versão para MacOS

A versão do Java em execução no seu sistema pode ser incompatível com o Ancestris, impedindo assim a sua execução. Receberá uma mensagem como a seguinte num terminal quando o Ancestris iniciar.

No exemplo a seguir, as instruções permitem pré-definir a Versão 8 (também conhecida como 1.8), sem remover o Java Versão 10:

**1/6 - Identifique a versão Java pré-definida**

```
java -version
```

[![image.png](https://docs.ancestris.org/uploads/images/gallery/2025-07/scaled-1680-/image.png)](https://docs.ancestris.org/uploads/images/gallery/2025-07/image.png)

Podemos ver a versão 10. O Ancestris não funcionará. Precisa da versão 8 (também conhecida como 1.8) ou 11 para o Ancestris.

**2/6 - Obtenha uma lista de todas as versões instaladas no seu sistema e verifique se a Versão 8 (também conhecida como 1.8) está entre elas**:

```
/usr/libexec/java_home -V
```

[![image.png](https://docs.ancestris.org/uploads/images/gallery/2025-07/scaled-1680-/NcGimage.png)](https://docs.ancestris.org/uploads/images/gallery/2025-07/NcGimage.png)

Podemos ver que as versões 10 e 1. 8 estão instaladas.  
Caso contrário, instale a versão 8, conforme explicado [nesta secção](#bkmrk-install-java "Instalar o Java").

**3/6 - Insira as 2 linhas seguintes no terminal**

```
echo 'export JAVA_HOME=`/usr/libexec/java_home -v 1.8`' >>~/.bash_profile
echo 'export jdkhome==`/usr/libexec/java_home -v 1.8`' >>~/.bash_profile
```

Estas duas linhas adicionarão o comando para pré-definir a sua versão Java no seu perfil pessoal.

A primeira linha pré-define a versão Java para todos os programas (JAVA\_HOME, em maiúsculas).

A segunda linha pré-define a versão Java a usar pelo Ancestris (jdkhome, minúsculas).

**4/6 - Feche o terminal**

```
exit
```

**5/6 - Reabra um terminal e verifique se o Java em execução é a versão 8**

```
java -version
```

[![image.png](https://docs.ancestris.org/uploads/images/gallery/2025-07/scaled-1680-/8hkimage.png)](https://docs.ancestris.org/uploads/images/gallery/2025-07/8hkimage.png)

Está bem. Podemos ver a versão 8 (também conhecida como 1.8). Agora pode iniciar o Ancestris.

**6/6 - Iniciar o Ancestris num terminal**

Quando o Ancestris inicia, pode ver na barra de título que o Ancestris está a utilizar a versão 8 do Java.

### Pré-definir a versão para Windows

Tem de criar um ficheiro BAT para cada versão Java que deseja manter.

Use o seu editor de texto favorito para criar estes ficheiros, usando o código abaixo, e coloque-os numa pasta disponível no seu PATH.

**JAVA8.BAT**

```
@echo off
echo Setting JAVA_HOME
set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_12
echo setting PATH
set PATH=C:\Program Files\Java\jdk1.8.0_12\bin;%PATH%
echo Display java version
java -version
```

**JAVA11.BAT**

```
@echo off
echo Setting JAVA_HOME
set JAVA_HOME=C:\Program Files\Java\jdk1.11.0_11
echo setting PATH
set PATH=C:\Program Files\Java\jdk1.11.0_11\bin;%PATH%
echo Display java version
java -version
```

Ao criar estes ficheiros, especifique o nome correcto para os ficheiros Java, que serão utilizados nas linhas JAVA\_HOME, dependendo da sua instalação Java

Ao decidir alterar a versão do Java, basta executar o ficheiro BAT correspondente: JAVA8 para a versão 1.8 ou JAVA11 para a versão 11. A versão do Java em uso será mostrada no terminal.

Para verificar se a alteração está realmente em vigor, digite java -version num terminal ou verifique [esta página](https://www.java.com/pt/download/help/version_manual.xml "Manual do Java").

Se deseja manter a versão mais recente do Java e forçar o uso de outra versão do Java pelo Ancestris, é necessário alterar o [ficheiro de configuração](https://docs.ancestris.org/books/manual-do-utilizador/page/ficheiros-de-programa-e-ficheiros-de-configura%C3%A7%C3%A3o-do-utilizador "Ficheiros de programa e ficheiros de configuração do utilizador"), linha `jdkhome="C:\caminho\para\o\java" `

<p class="callout warning">Caso o **Ancestris** tenha dificuldade em detectar a versão Java, pode editar esta mesma linha no ficheiro de configuração pré-definido, localizado na pasta de instalação: &lt;*pasta de instalação*&gt;/etc/ancestris.conf.  
Não esquecer de apagar o carácter # no início da linha.</p>

### Pré-definir a versão para Linux

Digite o seguinte numa consola:

```
sudo update-alternatives --config java
```

[![en_linux-java-versions.png](https://docs.ancestris.org/uploads/images/gallery/2020-05/scaled-1680-/en_linux-java-versions.png)](https://docs.ancestris.org/uploads/images/gallery/2020-05/en_linux-java-versions.png)

Seleccione na lista a versão requerida.

Se deseja manter a versão mais recente do Java e forçar o uso de outra versão do Java pelo Ancestris, é necessário alterar o [ficheiro de configuração](https://docs.ancestris.org/books/manual-do-utilizador/page/ficheiros-de-programa-e-ficheiros-de-configura%C3%A7%C3%A3o-do-utilizador "Ficheiros de programa e ficheiros de configuração do utilizador"), linha `jdkhome="/caminho/para/o/java" `

Para obter ajuda com esta ferramenta:

```
sudo update-alternatives -l
```