> ## 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](https://villagesql.com/docs/pt-BR/9.7/stable/source.md) 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 um subconjunto do VillageSQL:**

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

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

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

Execute os testes como um usuário comum, não como root: como root, o executor de testes pula alguns testes e um deles falha.

> [!NOTE]
>
> **--suite vs --do-suite:**
>
> * `--suite=villagesql/insert` executa um subconjunto
> * `--do-suite=villagesql` executa todos os testes, incluindo os subconjuntos (insert, select, stored\_procedure, etc.)
> * `--nounit-tests` pula os testes de unidade que o MTR executaria junto com a suíte. Esses são testes de unidade do MySQL upstream e incluem falhas conhecidas; execute os do VillageSQL separadamente com os comandos de [Testes de Unidade](#unit-tests) acima.

### Executando Testes Individuais

Execute um teste específico pelo nome:

```bash theme={null}
./mysql-test-run.pl villagesql/startup.recovery_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/startup.recovery_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.

### Portabilidade de Testes

Quando a saída de um teste inclui caminhos do diretório temporário do executor de testes, adicione esta diretiva antes de cada instrução que imprime um deles, 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 gravadas no log de erros em `--log-error-verbosity=3`, que o MTR define por padrão. Para definir o nível em uma execução:

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

O log de erros completo fica em `mysql-test/var/log/mysqld.1.err` em uma execução com um único worker. Sob `--parallel`, cada worker escreve em `mysql-test/var/<N>/log/mysqld.1.err` em vez disso.

Para escrever testes de regressão de extensões, consulte [Testes em C++](https://villagesql.com/docs/pt-BR/sdk/cpp/testing.md).

## Instalando Binários

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

```bash theme={null}
cmake --build "$HOME/build/villagesql" --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 "$HOME/villagesql-server" -B "$HOME/build/villagesql" -DCMAKE_INSTALL_PREFIX=/opt/villagesql
cmake --build "$HOME/build/villagesql" --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.


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