> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Compilar a Partir do Código-Fonte

> Compile o VillageSQL Server para MySQL a partir do código-fonte e comece a usar extensões.

## Visão geral

Compilar o VillageSQL a partir do código-fonte oferece a você os recursos mais recentes e permite personalizar a compilação para o seu ambiente específico.

Estes passos compilam o VillageSQL sobre o MySQL 8.4 upstream. O VillageSQL também é compilado sobre o Percona Server como base de código alternativa — consulte a página [Primeiros Passos com o Percona Server](https://villagesql.com/docs/pt-BR/8.4/stable/percona.md).

## Pré-requisitos

Antes de começar, certifique-se de ter os seguintes itens instalados:

* **Git** - Para clonar o repositório
* **Uma plataforma compatível** - Debian ou Ubuntu Linux, ou macOS com [Homebrew](https://brew.sh)

O repositório inclui um script que instala o CMake e as bibliotecas de desenvolvimento necessárias para a compilação. No Linux, ele também instala o compilador; no macOS, as Xcode Command Line Tools o fornecem. O Passo 2 executa esse script, portanto você não
precisa instalar esses pacotes por conta própria.

## Passo 1: Clonar o repositório

Clone o repositório do VillageSQL Server a partir do GitHub. Clone para o seu diretório pessoal (home) para que os passos do CMake abaixo funcionem sem modificações:

```bash theme={null}
cd "$HOME"
git clone --depth 1 -b publish/mysql-8.4_0.0.7 https://github.com/villagesql/villagesql-server.git
cd villagesql-server
```

> [!NOTE]
>
> O repositório ocupa vários GB por conta da base de código do MySQL.

## Passo 2: Instalar as dependências de compilação

Execute o script de configuração a partir do repositório que você acabou de
clonar. O script detecta o seu sistema operacional e instala os pacotes
necessários para a compilação:

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/setup_build_env.sh
```

No Linux, o script usa o `apt-get` e solicita `sudo`. No macOS, ele usa o
Homebrew. A CI do VillageSQL instala as suas dependências de compilação com o
mesmo script, portanto a lista de pacotes permanece atualizada em relação à
compilação.

> [!NOTE]
>
> O script é compatível com Debian ou Ubuntu Linux e com macOS. Em outra
> distribuição Linux, leia `villagesql/bld_tools/setup_linux_build_env.sh` e
> instale os pacotes equivalentes com o seu próprio gerenciador de pacotes.

## Passo 3: Configurar com o CMake

Crie um diretório de compilação fora do repositório e configure o projeto:

```bash theme={null}
# Create build directory (outside the repo)
mkdir -p "$HOME/build/villagesql"
cd "$HOME/build/villagesql"

# Configure with CMake
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1
```

No macOS, informe também o diretório do OpenSSL 3. O `openssl` sem versão do Homebrew agora é o OpenSSL 4, e o servidor não compila com ele:

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
  -DWITH_SSL="$(brew --prefix openssl@3)"
```

> [!NOTE]
>
> Os caminhos usam `$HOME` em vez de `~` em todo o documento, nas duas
> plataformas. O shell só expande `~` no início de uma palavra, portanto
> `--datadir=~/mysql-data/data` chega ao `mysqld` como um diretório literalmente
> chamado `~` e o servidor é abortado. As aspas em `"$HOME/..."` também mantêm o
> caminho íntegro caso o nome do seu diretório pessoal contenha um espaço.
> Substitua o caminho do repositório pela localização real do seu clone, se for
> diferente.

### Opções do CMake explicadas

* `"$HOME/villagesql-server"` - Caminho para o repositório clonado do VillageSQL
* `-DWITH_DEBUG=1` - Compila com o mecanismo DBUG e as asserções ativados, sem otimização (recomendado para desenvolvimento)
* `-DWITH_SSL="$(brew --prefix openssl@3)"` - Aponta o cmake para o OpenSSL 3. O Passo 2 instala o `openssl@3`. Se você pulou o Passo 2, execute `brew install openssl@3` antes, porque `brew --prefix openssl@3` imprime um caminho mesmo quando o pacote não está instalado, e o cmake então para com `Wrong option or path for WITH_SSL=`.

### Opções adicionais do CMake

**Compilação de produção:**

```bash theme={null}
cmake "$HOME/villagesql-server"
```

**Com comentário de compilação personalizado:**

```bash theme={null}
cmake "$HOME/villagesql-server" -DWITH_DEBUG=1 \
      -DCOMPILATION_COMMENT="VillageSQL Version of MySQL"
```

> [!NOTE]
>
> Se precisar reconfigurar, limpe primeiro o cache do CMake (execute a partir do diretório de compilação):
>
> ```bash theme={null}
> rm CMakeCache.txt
> ```

## Passo 4: Compilar o código

Compile o VillageSQL usando make com compilação paralela. A partir do diretório de compilação:

**Compilar tudo (recomendado):**

```bash theme={null}
make -j10
```

Isso compila o servidor, o cliente `mysql` usado no
[Passo 7](#step-7-connect-with-mysql-client), o SDK de Extensões e os arquivos
`.veb` das extensões de exemplo.

**Compilar somente o servidor e o cliente:**

```bash theme={null}
make -j10 mysqld mysql
```

Esse par é mais rápido e não compila o SDK de Extensões nem os arquivos `.veb`
de exemplo, portanto `INSTALL EXTENSION vsql_complex` não encontra nenhum
pacote para instalar e uma compilação de extensão que passa
`-DVillageSQL_BUILD_DIR` não encontra o SDK.

> [!TIP]
>
> Ajuste o paralelismo (`-j10`) de acordo com os núcleos da sua CPU. Subtraia de 2 a 4 do total de núcleos para manter o sistema responsivo. Por exemplo, em uma máquina de 12 núcleos, use `-j10`.

Quando concluir, verifique se os binários do servidor e do cliente foram compilados:

```bash theme={null}
ls "$HOME/build/villagesql/bin/mysqld" "$HOME/build/villagesql/bin/mysql"
```

## Passo 5: Inicializar o banco de dados

Antes de iniciar o servidor pela primeira vez, inicialize o diretório de dados:

Produção (com senha gerada - recomendado):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

Desenvolvimento (sem senha - opcional):

```bash theme={null}
mkdir -p "$HOME/mysql-data/data"
"$HOME/build/villagesql/bin/mysqld" --initialize-insecure --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

> [!NOTE]
>
> Use `--initialize` (com senha) para configurações semelhantes às de produção. Use `--initialize-insecure` (sem senha) apenas para desenvolvimento e testes locais. Ao usar `--initialize`, uma senha temporária será gerada e exibida no console: `A temporary password is generated for root@localhost: <password>`

Verifique se a inicialização foi bem-sucedida conferindo se os bancos de dados de sistema foram criados:

```bash theme={null}
ls "$HOME/mysql-data/data/mysql"
```

## Passo 6: Iniciar o servidor

Inicie o servidor VillageSQL:

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

**Executando como root (Docker ou sudo):**

```bash theme={null}
"$HOME/build/villagesql/bin/mysqld" --user=root --gdb --datadir="$HOME/mysql-data/data" --basedir="$HOME/build/villagesql"
```

> [!TIP]
>
> A flag `--gdb` desbloqueia o `SIGINT`, então Ctrl-C interrompe o servidor quando você o executa a partir de um terminal. Ela também suprime o backtrace de falha e anula `--core-file`, então não a use quando precisar de um relatório de falha. Para executar em segundo plano, adicione `--daemonize` ao comando `mysqld`.

## Passo 7: Conectar com o cliente MySQL

Abra um novo terminal e conecte-se ao servidor usando o cliente MySQL:

Se estiver usando --initialize-insecure (sem senha):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root
```

Se estiver usando --initialize (com senha gerada):

```bash theme={null}
"$HOME/build/villagesql/bin/mysql" -u root -p
# Enter the temporary password printed during initialization
```

Você deverá ver o prompt do MySQL:

```
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: <version> Source distribution

mysql>
```

### Alterar a senha do root

Se você usou `--initialize`, altere a senha temporária:

```sql theme={null}
SET PASSWORD = 'your-secure-password';
```

### Verificar a instalação

Verifique se você está executando o VillageSQL:

```sql theme={null}
SELECT VERSION();
```

As compilações de desenvolvimento incluem o hash do commit do git na string de versão:

```
8.4.11-villagesql-0.0.7-dev-689c74a9-debug
```

## Passo 8: Configurar usuários e banco de dados

### Criar um usuário de desenvolvimento

Para o desenvolvimento diário, crie um usuário que não seja root:

```sql theme={null}
-- Create user
CREATE USER developer IDENTIFIED BY 'dev-password';

-- Grant all privileges
GRANT ALL PRIVILEGES ON *.* TO developer;
```

Saia e reconecte-se como o seu novo usuário:

```bash theme={null}
# Ctrl-D to exit
"$HOME/build/villagesql/bin/mysql" -u developer -p
```

### Criar um banco de dados

```sql theme={null}
CREATE DATABASE my_database;
USE my_database;
```

> [!TIP]
>
> Conecte-se a um banco de dados específico: `"$HOME/build/villagesql/bin/mysql" -u developer -p -D my_database`

## Passo 9: Executar os testes

Verifique a compilação com a suíte de testes do VillageSQL, a partir do diretório de compilação. Execute os testes como um usuário comum: como root, o executor de testes pula alguns testes, e um deles falha.

```bash theme={null}
cd "$HOME/build/villagesql"
mysql-test/mysql-test-run.pl --do-suite=villagesql --nounit-tests --parallel=auto
```

`--nounit-tests` pula os testes de unidade do MySQL upstream, que incluem falhas conhecidas. Execute os testes de unidade do VillageSQL separadamente:

```bash theme={null}
make -j10 villagesql-unit-tests && ctest -L villagesql
```

Um teste com falha faz qualquer um dos dois comandos sair com código diferente de zero.

Para depuração com GDB, execução de testes individuais, regravação dos resultados esperados e contribuição para a base de código do servidor, consulte o [Guia de Desenvolvimento do Servidor](https://villagesql.com/docs/pt-BR/8.4/stable/server-development.md).

## Compilar pacotes nativos (RPM/DEB)

`villagesql/bld_tools/build_deb.sh` e `build_rpm.sh` compilam um pacote Debian ou RPM
diretamente da árvore de código-fonte, para instalar com o seu gerenciador de pacotes
em vez de seguir os passos manuais acima. Nenhum dos dois precisa de uma configuração
prévia do CMake — ambos derivam a versão do pacote dos arquivos `VSQL_VERSION` e
`MYSQL_VERSION` na raiz do repositório. Com os Passos 1-2 já concluídos,
instale as ferramentas de empacotamento e as dependências de compilação que o Passo 2 deixa de fora — no
Debian/Ubuntu, `dpkg-dev`, `debhelper`, `libcurl4-openssl-dev`, `libsystemd-dev`
e `systemd-dev`; no Enterprise Linux, `rpm-build` — e então execute um deles a partir da
raiz do repositório:

```bash theme={null}
cd "$HOME/villagesql-server"
villagesql/bld_tools/build_deb.sh   # writes to ./debs
# or
villagesql/bld_tools/build_rpm.sh   # writes to ./rpms
```

De acordo com [villagesql-server#931](https://github.com/villagesql/villagesql-server/pull/931),
que adicionou essas ferramentas, o pacote resultante substitui uma instalação existente do MySQL
no host de destino em vez de ser instalado ao lado dela.

## Solução de problemas

### A compilação falha por dependências ausentes

Execute o script de configuração novamente. O [Passo 3](#step-3-configure-with-cmake)
deixa você no diretório de compilação, portanto informe o caminho absoluto do script:

```bash theme={null}
"$HOME/villagesql-server/villagesql/bld_tools/setup_build_env.sh"
```

Verifique a mensagem de erro para identificar a biblioteca ausente específica.

### O servidor não inicia

* Verifique se o diretório de dados foi inicializado: `ls "$HOME/mysql-data/data/"`
* Verifique se outra instância do MySQL/VillageSQL está usando a porta 3306
* Leia as mensagens que o `mysqld` exibe no seu terminal, ou inicie-o com `--log-error="$HOME/mysql-data/error.log"` e leia esse arquivo

### A instalação da extensão falha

* Certifique-se de que o arquivo `.veb` da extensão existe no diretório `veb_dir` (`$HOME/build/villagesql/lib/veb` para uma compilação a partir do código-fonte) e de que sua biblioteca se chama `<extension_name>.so` no Linux e no macOS
* Verifique se o VillageSQL tem as permissões necessárias para carregar extensões
* Verifique se o nome da extensão e o nome do arquivo .veb estão corretos

## Próximos passos

> [card] [Usando Extensões](https://villagesql.com/docs/pt-BR/extensions/install.md)
>
> Aprenda a instalar, atualizar e gerenciar extensões do VillageSQL.

> [card] [Criando Extensões](https://villagesql.com/docs/pt-BR/extensions/build/create.md)
>
> Crie suas próprias extensões personalizadas para o VillageSQL.

> [card] [Instalar](https://villagesql.com/docs/pt-BR/8.4/stable/install-server.md)
>
> Guia de início rápido para o VillageSQL.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.