Chet

Chet - C tradutor de cabeçalho para Delphi

O Chet é um tradutor .h-to-.pas alimentado por Libclang para Delphi.

Características

Ao contrário de outros tradutores de cabeçalho, o Chet usa o compilador CLANG para analisar arquivos de cabeçalho, resultando em traduções mais precisas que requerem menos ajustes manuais.

Alguns recursos notáveis são:

• Traduz tipos de dados C, como estruturas, união, enum, typedefs, tipos processuais e tipos opacos.
• Traduz funções C para procedimentos ou funções da Delphi.
• Tenta traduzir as declarações #define para constantes sempre que possível.
• Gera um único arquivo .pas para um diretório inteiro de arquivos .h . Isso reduz os problemas devido a dependências entre os arquivos do cabeçalho.
• Gera a saída para várias plataformas (Winsows, MacOS, Linux, iOS e Android), se desejado.
• Você pode personalizar o processo de análise de clang fornecendo argumentos da linha de comando ao compilador.
• Você pode personalizar a saída de algumas operações de conversão.
• Retém qualquer comentário de documentação no estilo doxygen, se desejado, ou os converte em comentários xmldoc ou comentários do PASDOC.
• Fornece uma GUI para configurar o processo de conversão e permite salvar as configurações de conversão em um arquivo de projeto .chet para reutilização.

Limitações

• O Chet funciona apenas com arquivos de cabeçalho C, não com arquivos de cabeçalho C ++.
• Todas as funções não-linhadas nos arquivos de cabeçalho são traduzidas e assumidas como disponíveis na biblioteca estática ou dinâmica do projeto. Isso não precisa ser o caso. (As funções inlinadas nunca são traduzidas, pois nunca estão disponíveis na biblioteca.)
• Como o CLANG é usado para analisar os arquivos do cabeçalho, isso significa que o pré -processador de Clangs também é executado para executar a análise condicional (guiada pelas diretivas #ifdef ). Isso é bom e ruim. É bom porque melhora a precisão da conversão. Mas pode ser ruim porque usa o sistema em que o Chet segue para determinar alguns caminhos condicionais. Por exemplo, como o Chet é executado no Windows, ele analisará o código nas seções #ifdef _WIN32 mas pule qualquer código nas seções para outras plataformas.

Requisitos

Como o Chet usa um compilador real, você precisará ter um (mínimo) C desenvolver um ambiente instalado, bem como o LLVM com o CLANG. Clang precisa ser capaz de encontrar os cabeçalhos do sistema para o ambiente de desenvolvimento. Geralmente, eles estarão disponíveis se você tiver alguma versão do Visual Studio com o Visual C ++ instalado. A edição gratuita (comunitária) do Visual Studio é suficiente.

Você pode executar o Chet primeiro para verificar se há erros relacionados à falta de dependências. Se você receber algum erro de dependência ao executar o tradutor, poderá fazer o download das dependências aqui:

• LLVM com Clang (Clang for Windows (64 bits) é recomendado).
• O Visual Studio IDE (a edição da comunidade gratuita é suficiente; certifique -se de instalar o suporte ao C ++).

Você pode usar o aplicativo Windows CHET de 64 bits pré-compilado no diretório Bin .

Se você deseja compilar o Chet, também precisará da Libclang para Delphi e verifique se o Delphi IDE pode encontrá -lo (o projeto Chet o encontrará automaticamente se o diretório Neslib.Clang estiver no mesmo nível do diretório Chet ).

Contribuições

Obrigado por essas contribuições:

• Michał Sznajder para melhorar as conversões de char.
• Chiptamer para adicionar suporte para declarações de const digitadas.
• Jarrod Davis por adicionar suporte de pós-processamento.
• Alexey.T por adicionar suporte para campos de bits embalados em estruturas C, mapeamentos de tipos definidos pelo usuário e a capacidade de ignorar determinados arquivos de cabeçalho.

Guia do usuário

Chet é bem direto. Em muitos casos, você só precisa fornecer um diretório com arquivos de cabeçalho, o nome do arquivo .pas de saída e selecionar "Executar o Tradutor de cabeçalho (F9)".

Para obter mais controle sobre o processo de conversão, você pode especificar várias opções, descritas abaixo.

Menu

Quaisquer opções de configuração definidas podem ser salvas em um arquivo de configuração .chet (que é um arquivo ini simples). Isso permite que você carregue as configurações posteriormente para executar novamente a conversão (por exemplo, quando novas versões dos arquivos de cabeçalho foram lançadas). Você pode carregar e salvar essas opções de configuração usando o menu File .

Para ajudar a pré-configurar algumas configurações para uma nova sessão, selecione File | New Project... (Ctrl+N) . Você insere o nome do projeto e o CHET pré-configurará algumas configurações com base no nome que você entra (embora você sempre possa modificar essas configurações posteriormente).

O menu Run assim como a única opção Run Header Translator , que você também pode ativar com F9 .

Página do projeto

A página do projeto contém as opções de configuração mais importantes:

• Diretório com arquivos de cabeçalho C : Especifique o diretório com os arquivos de origem .h aqui. O diretório pode ser relativo ao diretório que contém o arquivo do projeto .chet . Clique no botão ... para navegar para obter um diretório. É recomendável que você não use o diretório com o código -fonte C original. Em vez disso, copie os arquivos do cabeçalho para um diretório separado apenas para fins de conversão. Isso facilita a exclusão de arquivos de cabeçalho que você não deseja converter ou para fazer edições em arquivos de cabeçalho para fins de conversão.
• Inclua subdiretos : verifique esta caixa se os arquivos do cabeçalho estiverem espalhados por vários diretórios. Nesse caso, o Chet também pesquisará todos os subdiretos do diretório fornecido.
• Arquivo Pascal Target : Especifique o nome do arquivo .pas que será gerado. I Single Combined Pascal File será gerado para todos os arquivos de cabeçalho analisado. O nome pode ser relativo ao diretório que contém o arquivo do projeto .chet . Clique no botão ... para abrir uma caixa de diálogo Salvar.
• Lista de unidade separada por vírgula para "usar" : se os arquivos de cabeçalho dependem de declarações em algumas outras unidades Delphi (como Windows.Winapi ), você poderá listar essas unidades aqui. O será adicionado à cláusula de uso do arquivo Pascal gerado.

Página de plataformas

Nesta página, você especifica quais plataformas deseja segmentar e como deseja configurá -las.

• Biblioteca constante : especifique o nome da constante para usar para o nome da biblioteca. Por exemplo, se você tiver uma biblioteca chamada "mylib.dll", o nome dessa constante pode ser LIB_MYLIB , para que a seguinte declaração será gerada: const LIB_MYLIB = 'mylib.dll' .

Em seguida, são caixas de seleção para todas as plataformas que você deseja direcionar (Windows de 32 bits, Windows de 64 bits, macOS de 32 bits, Linux de 64 bits, iOS e Android). Para cada plataforma que você verifica, você deve inserir as seguintes opções:

• Nome da biblioteca : o nome da biblioteca dinâmica ou estática para a plataforma **. **
• Prefixo (_pu) : o nome da função prefixo a ser usado para a plataforma. Isso geralmente pode ser deixado vazio. Mas, dependendo de como a biblioteca é construída, todos os nomes de funções podem ser prefixados (geralmente com um caractere _ ).

Página de opções de análise

Aqui você pode personalizar o processo de análise Clang.

• Ignore erros de análise : verifique esta caixa para ignorar quaisquer erros de análise e tente traduzir os arquivos do cabeçalho de qualquer maneira. Observe que isso pode levar à saída incorreta, para que você geralmente deve deixar essas opções desmarcadas. Você pode achar essa opção útil como uma opção temporária para verificar erros de análise. Normalmente, Clang interrompe a análise depois de encontrar o primeiro erro fatal. Ao verificar esta caixa, ele mostrará todos os erros de análise (até um limite), para que você possa abordá -los e desmarcar esta caixa novamente.
• Argumentos da linha de comando para passar para Clang : Especifique qualquer argumento da linha de comando para passar para o compilador CLANG aqui. Geralmente, não há necessidade disso, mas alguns projetos C podem exigir alguns argumentos da linha de comando para que a análise seja bem -sucedida. Os argumentos da linha de comando mais comuns que você pode precisar é adicionar o pré -processador ( -D<define> ) e incluir caminhos de pesquisa ( -I<path> ). Existem botões separados para facilitar adicioná -los. Consulte a documentação do CLANG para obter informações sobre os argumentos de linha de comando disponíveis.

Opções de conversão

É aqui que você personaliza a saída gerada.

• Convenção de chamada : especifique a convenção de chamada para usar para todas as funções traduzidas. Você pode escolher entre cdecl e stdcall . Em quase todos os casos, você deve usar a convenção de chamada cdecl padrão. Use stdcall apenas para DLLs de Windows de 32 bits, que você sabe que são compilados com a Convenção de Calling STDCALL. Geralmente são apenas as DLLs do sistema Windows. A maioria das DLLs de terceiros usam CDECL.
• Manuseio de comentários : Aqui você especifica como lidar com comentários de documentação (consulte também comentários abaixo):
  • Mantenha os comentários como é (padrão): não converta os comentários, mas mantenha-os no estilo original (doxygen).
  • Remover comentários : Todos os comentários serão removidos.
  • Converta comentários no estilo xmldoc (experimental) : converte comentários no estilo doxygen em comentários de estilo xmldoc (o estilo de documentação padrão para Delphi). Esse recurso ainda está em construção e considerado experimental.
  • Converta comentários em estilo pasdoc (experimental) : converte comentários no estilo doxygen em comentários no estilo pasdoc. Esse recurso ainda está em construção e considerado experimental.
• Converter "char" para : o tipo C char é ambíguo, pode ser usado como um número inteiro de 8 bits ou um caractere em uma string de texto. As versões digitadas signed char e unsigned char são sempre convertidos em Shortint e Byte , respectivamente. Mas quando nenhum assinado é especificado, você tem as seguintes opções:
  • Utf8char (padrão): converta char em um UTF8Char cruzado.
  • Shortint : converta char em um Shortint assinado de 8 bits.
  • Byte : converta char em um Byte não assinado de 8 bits.
• Manuseio de palavras reservadas : os arquivos de cabeçalho podem usar identificadores que conflitam com palavras reservadas em Delphi (como begin e procedure ). Aqui você especifica como deseja converter esses identificadores:
  • Adicione líder '&' (padrão): prefixo o identificador com um ampersand.
  • Adicione líder '_' : prefixo o identificador com um sublinhado.
  • Adicione '_' à direita : adicione um sublinhado ao final do identificador.
• Trate as diretrizes como palavras reservadas : se deve tratar as diretivas Delphi como palavras reservadas (verificadas por padrão). Tecnicamente, você pode usar muitas diretivas (como public ) como identificadores em Delphi, mas parece estranho e a sintaxe do Delphi os trata de maneira diferente. Portanto, você geralmente deseja tratá -las como palavras reservadas também.
• Manipulação de enum : você tem a opção de converter enumes C de duas maneiras:
  • Converter para o tipo enumerado (padrão): converta em um tipo enumerado Delphi.
  • Converta em tipo inteiro e constantes : converta o nome do tipo em um número inteiro (como no type MyEnum = Integer; ) e crie constantes para cada opção na enumeração. Isso pode ser mais aplicável a algumas bibliotecas.
• Declarações incontroláveis : Apesar dos melhores esforços, o Chet pode não ser capaz de converter todas as declarações (especialmente #define , veja as observações abaixo). Aqui você especifica como lidar com isso:
  • Escreva item TODO TODO padrão): grava um comentário para o código-fonte Delphi, bem como uma versão comentada da declaração original. Lembre -se de que você pode visualizar uma lista de todos os TODOs no Delphi IDE selecionando View | Tool Windows | To-Do List .
  • Comente a declaração original : escreve uma versão comentada da declaração original para o código-fonte Delphi.
  • Ignore a declaração : ignora a declaração e não escreve nada para o código -fonte Delphi.

Observe que apenas os comentários da documentação no estilo doxygen são analisados por Clang. Estes são comentários que seguem qualquer uma dessas convenções de formato:

• /// Comment (with 3 slashes)
• /** Comment (with two stars) */
• /*! Comment (with exclamation point) */
• ///< Comment (applies to preceding declaration)
• /**< Comment (applies to preceding declaration) */
• /*!< Comment (applies to preceding declaration) */

Chet tenta converter #define declarações em constantes, se possível. Isso só funciona se:

• A definição não é semelhante à função. Isto é, macros como #define ABS(x) (x < 0) ? -x : x não pode ser traduzido.
• A defina usa uma expressão que apenas usa outros define e literais. Por exemplo: #define FOO 3<<BAR será convertido em const FOO = 3 shl BAR .

Ignorar a página

Aqui você pode especificar uma lista de símbolos para ignorar. Esses símbolos não serão traduzidos.

O uso mais comum é ignorar o #define que gera erros de conversão ou funções que você não precisa. Você também pode optar por ignorar alguns tipos, mas isso pode resultar em erros de compilação posteriormente porque os tipos esperados estão faltando.

Observe que os símbolos são sensíveis ao minúsculas.

Traduzir página

A página final possui um único botão "Executar o tradutor do cabeçalho" (que você também pode ativar com F9 ). Ele mostra o progresso do processo de tradução, bem como quaisquer erros que ocorreram ao analisar os arquivos do cabeçalho.

Você pode usar esses erros para corrigir os arquivos do cabeçalho, adicionar arquivos de cabeçalho ausentes ou configurar esse processo de análise, adicionando argumentos da linha de comando (por exemplo, adicionando caminhos de pesquisa incluem).

Licença

O Chet é licenciado sob a licença BSD simplificada. Consulte License.txt para obter detalhes.