> ## 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.

# Guia de Desenvolvimento do Servidor

> Depuração, testes e contribuição para a base de código do servidor VillageSQL.

Este guia aborda a depuração, a execução do conjunto de testes do servidor e a contribuição para o VillageSQL. Ele pressupõe uma compilação de código-fonte funcional; consulte [Compilar a Partir do Código-Fonte](/docs/pt-BR/mysql-8.4/0.0.5/source) se você ainda não fez isso.

## Depuração

A depuração do servidor VillageSQL usa GDB no Linux e lldb no macOS. O GDB no macOS requer assinatura de código, o que é trabalhoso de configurar; o lldb é o depurador padrão do macOS e funciona imediatamente.

### Linux (GDB)

Execute o VillageSQL sob o GDB:

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

**Dentro do GDB:**

```
(gdb) run                    # Start the server
(gdb) break function_name    # Set breakpoints
(gdb) continue               # Resume execution
(gdb) bt                     # Show backtrace on crash
```

**Comandos GDB comuns:**

```
# Break on specific SQL command execution
(gdb) break mysql_execute_command

# Break on extension loading
(gdb) break Sql_cmd_install_extension::execute

# Print variable values
(gdb) print variable_name

# Step through code
(gdb) step      # Step into functions
(gdb) next      # Step over functions
```

### macOS (lldb)

Execute o VillageSQL sob o lldb:

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

**Dentro do lldb:**

```
(lldb) run                         # Start the server
(lldb) breakpoint set -n function_name  # Set breakpoints
(lldb) continue                    # Resume execution
(lldb) bt                          # Show backtrace on crash
```

**Comandos lldb comuns:**

```
# Break on specific SQL command execution
(lldb) breakpoint set -n mysql_execute_command

# Break on extension loading
(lldb) breakpoint set -n Sql_cmd_install_extension::execute

# Print variable values
(lldb) print variable_name

# Step through code
(lldb) step      # Step into functions
(lldb) next      # Step over functions
```

## Executando Testes

O VillageSQL inclui tanto testes de unidade quanto testes de regressão para verificar a funcionalidade.

### Testes de Unidade

Execute os testes de unidade específicos do VillageSQL (de dentro do seu diretório de compilação):

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

Ou execute todos os testes de unidade:

```bash theme={null}
ctest --output-on-failure
```

### Testes de Regressão

Vá para o diretório mysql-test:

```bash theme={null}
cd mysql-test
```

**Execute o conjunto de testes completo do MySQL (lento):**

```bash theme={null}
./mysql-test-run.pl --parallel=auto
```

**Execute apenas os testes específicos do VillageSQL:**

```bash theme={null}
./mysql-test-run.pl --suite=villagesql
```

**Execute os testes do VillageSQL incluindo todos os subconjuntos:**

```bash theme={null}
./mysql-test-run.pl --do-suite=villagesql --parallel=auto
```

<Note>
  **--suite vs --do-suite:**

  * `--suite=villagesql` executa apenas os testes villagesql de nível superior
  * `--do-suite=villagesql` executa todos os testes, incluindo os subconjuntos (insert, select, stored\_procedure, etc.)
</Note>

### Executando Testes Individuais

Execute um teste específico pelo nome:

```bash theme={null}
./mysql-test-run.pl villagesql.complex_index
```

Execute um teste de um subconjunto:

```bash theme={null}
./mysql-test-run.pl --suite=villagesql/insert
```

### Atualizando Resultados de Testes

Se você alterou a funcionalidade e precisa atualizar a saída esperada dos testes:

```bash theme={null}
./mysql-test-run.pl --record villagesql.complex_index
```

<Warning>
  **Gravação de Testes:** Sempre revise as alterações nos arquivos `.result` para garantir que elas reflitam o comportamento pretendido, e não bugs. A flag `--record` sobrescreve cegamente a saída esperada.
</Warning>

### Portabilidade de Testes

Quando a saída de um teste inclui caminhos do diretório temporário do executor de testes, adicione esta diretiva dentro do seu arquivo `.test` para que os resultados gravados não contenham caminhos absolutos que quebram em outras máquinas:

```sql theme={null}
--replace_result $MYSQLTEST_VARDIR MYSQLTEST_VARDIR
```

### Depurando Falhas de Testes

As mensagens de log específicas do VillageSQL (emitidas via `LogVSQL()`) são suprimidas por padrão. Para exibi-las no log de erros durante uma execução de teste:

```bash theme={null}
./mysql-test-run.pl --mysqld=--log-error-verbosity=3 villagesql.complex_index
```

O log de erros completo fica em `mysql-test/var/log/mysqld.1.err`.

Para escrever testes de regressão de extensões, consulte o [Desenvolvimento em C++](/docs/pt-BR/mysql-8.4/0.0.5/development).

## Instalando Binários

Para instalar o VillageSQL em todo o sistema (requer as permissões apropriadas):

```bash theme={null}
cmake --build build --target install
```

Isso instala os binários em `/usr/local/mysql/` por padrão. Você pode personalizar o prefixo de instalação:

```bash theme={null}
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build build --target install
```

## Contribuindo

Se você está contribuindo para o VillageSQL, consulte as [diretrizes de contribuição](https://github.com/villagesql/villagesql-server/blob/main/CONTRIBUTING.md) para conhecer os padrões de codificação e os fluxos de trabalho de desenvolvimento.