clang_libraries_companion
v0.2.0
Este repositório contém todos os exemplos de código associados ao seguinte deck de slide:
O slide deck está disponível para download em:
O repositório está organizado da seguinte maneira:
Cada exemplo de código ou grupo de exemplos de código é estruturado como um projeto CMake separado. Isso permite que os usuários experimentem um exemplo de código individual sem precisar criar todos os exemplos de código. Por conveniência, são fornecidos dois arquivos cmakelists.txt que criam todos os seus projetos subordinados. Todos os projetos podem ser construídos usando um script de construção fornecido (que chama esses dois Superbuilds CMake).
Este repositório emprega um fluxo de trabalho de IC com base nas ações do GitHub. Cada vez que um novo compromisso é empurrado, os exemplos de código no repositório são construídos e executados como um teste básico de sanidade. Esse fluxo de trabalho do CI serve como um exemplo para mostrar como os pacotes APT LLVM/CLANG Ubuntu que são fornecidos pelo projeto LLVM (em https://apt.llvm.org/) podem ser usados nos corredores Linux do Github-Hosted. O fluxo de trabalho do IC atualmente se constrói para algumas combinações do seguinte:
Os exemplos de código têm as seguintes dependências de software:
Essas dependências devem ser instaladas antes da criação dos exemplos de código.
Se a biblioteca padrão C ++ não suportar o formato STD ::, uma versão personalizada da biblioteca FMT poderá ser instalada automaticamente (como parte do processo de compilação) para fornecer esse suporte. (Esta versão personalizada da biblioteca FMT fornece um cabeçalho de biblioteca padrão chamado "Format" e coloca algumas declarações importantes no espaço de nome de STD nesse cabeçalho.) A biblioteca padrão C ++ incluída na versão 13 e acima do GCC tem suporte para STD :: Format.
Por conveniência, é fornecido um Dockerfile para criar um ambiente de contêiner que inclua todas as dependências de software necessárias. Mais informações sobre este dockerfile são fornecidas em uma seção posterior.
Os exemplos de código empregam um processo de construção baseado em cmake. Cada exemplo de código ou grupo de exemplos relacionados é estruturado como um projeto CMake separado. Por conveniência, é fornecido um script para criar todos os exemplos de código em uma etapa.
Alguns dos exemplos de código requerem formato STD :: (introduzido em C ++ 20). Se a implementação da biblioteca padrão C ++ que está sendo usada não suportar o formato STD ::, uma versão personalizada da biblioteca FMT poderá ser instalada automaticamente (como parte do processo de compilação) para fornecer esse suporte.
Para construir todos os exemplos de código (e opcionalmente executar todas as demos associadas), faça o seguinte:
Inicialize o ambiente de modo que as dependências de software necessárias (por exemplo, executáveis, cabeçalhos ou bibliotecas) sejam encontradas com sucesso no horário de construção. Essa etapa normalmente é necessária apenas se algumas das dependências de software forem instaladas em locais onde normalmente não seriam encontrados pelo processo de construção. Quando esta etapa é necessária, pode parecer algo como o seguinte:
# Initialize the following variables used to configure the
# environment:
# cmake_dir
# - The directory under which CMake has been installed
# (e.g., /usr, /usr/local).
# clang_dir
# - The directory under which LLVM/Clang has been installed
# (e.g., /usr, /usr/local).
# gcc_dir
# - The directory under which GCC has been installed
# (e.g., /usr, /usr/local).
# boost_dir
# - The directory under which Boost has been installed
# (e.g., /usr, /usr/local).
# Use the preceding variables to configure the environment by
# setting several key environment variables:
export BOOST_INCLUDEDIR=$boost_dir/include
export BOOST_LIBRARYDIR=$boost_dir/lib
export PATH=$cmake_dir/bin:$clang_dir/bin:$gcc_dir/bin:$PATH
export LD_LIBRARY_PATH=$BOOST_LIBRARYDIR:$LD_LIBRARY_PATH
export CPATH=$boost_dir/include:$CPATH
Defina o diretório de trabalho atual para o diretório de nível superior da árvore de trabalho do repositório Git clonado.
Invoque o script de construção com as opções apropriadas. Nominalmente, o script é chamado da seguinte maneira:
./build --defaults
Se a biblioteca padrão C ++ que está sendo usada suporta o formato STD ::, a opção "-no-fmt" poderá ser adicionada à invocação do script de compilação acima (para que a versão personalizada da biblioteca FMT não seja usada). Isto é, o seguinte comando pode ser usado:
./build --defaults --no-fmt
O script de construção suporta inúmeras opções. Para obter informações detalhadas sobre o uso, invoco o script com a opção "-h" ou "-help". Os argumentos da linha de comando são processados em ordem da esquerda para a direita. Portanto, no caso em que uma configuração é estabelecida por mais de uma opção de linha de comando, a configuração da opção mais à direita entra em vigor.
Se desejar, execute os scripts de demonstração (como um teste básico de sanidade) com o comando:
./build --demo
A saída do processo de construção é colocada nos diretórios:
A saída para cada projeto CMake é colocada em um diretório com o mesmo nome desse projeto. Por exemplo, a saída de compilação para o projeto chamada Cyclomatic_Complexity dos exemplos de convés de slides é colocada no diretório:
slides/examples/tmp_build/cyclomatic_complexity
A maioria dos projetos possui um script de demonstração (chamado "Demo" ou com um nome contendo "Demo"). Por exemplo, para executar o script de demonstração para o projeto Cyclomatic_complexity, use o comando:
slides/examples/tmp_build/cyclomatic_complexity/demo
É fornecido um DockerFile que pode ser usado para criar um contêiner podman/docker com todas as dependências de software necessárias para criar e executar os exemplos de código neste repositório. As instruções são fornecidas abaixo sobre como usar esse ambiente de contêiner. Embora essas instruções usem (sem raiz) Podman, os programas de podman e docker têm interfaces quase idênticas da linha de comando. Portanto, deve ser possível substituir o "Docker" por "Podman" nas instruções.
Vamos $ top_dir denotar o diretório de nível superior da árvore de trabalho do repositório Git clonado (ou seja, o diretório que contém o arquivo chamado readme.md que você está lendo no momento). Observe que $ top_dir deve ser um caminho absoluto.
Defina o diretório de trabalho para o diretório de nível superior da árvore de trabalho usando o comando:
cd $TOP_DIR
Construa o contêiner usando o comando:
podman build --tag cl-demo - < podman/Dockerfile
Crie uma instância temporária do contêiner e execute um shell bash no contêiner usando o comando:
podman run -i -t --rm -v $TOP_DIR:$TOP_DIR:rw -w $TOP_DIR
--cap-add=SYS_PTRACE --security-opt label=disable
cl-demo /bin/bash
Observe que as opções "--CAP-ADD" e "--Security-OPT" podem não ser necessárias.
Se você não deseja que o contêiner seja excluído depois que o shell bash é excitado, omite a opção "--rm".
Prossiga para construir e executar os scripts de demonstração, conforme descrito em detalhes em uma seção anterior. Por exemplo, pode -se invocar o seguinte comando do Bash Shell em execução no contêiner:
./build --defaults
Às vezes, o uso do desinfetante de endereço (ASAN) pode ser problemático, devido, por exemplo, para peculiar a plataforma em que o código está sendo executado. O comportamento de tempo de execução do ASAN pode ser controlado através da variável de ambiente asan_options, cujo valor é uma lista separada pelo cólon de pares de valores-chave (por exemplo, "Verbososy = 1: detect_leaks = 0").
Em algumas plataformas, algumas das bibliotecas usadas pelos exemplos de código foram observadas como tendo vazamentos de memória. Se asan reclamarem de algumas bibliotecas com vazamentos de memória, a detecção de vazamentos de memória poderá ser desativada adicionando "detect_leaks = 0" à lista de opções ASAN na variável ASAN_OPTions Environment. Por exemplo, asan_options podem ser definidas da seguinte forma:
ASAN_OPTIONS=detect_leaks=0
Parece que o envenenamento por memória do usuário às vezes pode resultar em falsos positivos da ASAN (a saber, erros de uso-pó), dependendo de como o LLVM/CLANG foi construído. Provavelmente, isso se deve a inconsistências na maneira como o envenenamento pelo usuário é tratado nas bibliotecas LLVM/CLANG e no aplicativo usando essas bibliotecas. Se esse problema for encontrado, o envenenamento pelo usuário poderá ser desativado adicionando "allow_user_poisoning = 0" à lista de opções ASAN na variável ASAN_OPTions Environment. Por exemplo, asan_options podem ser definidas da seguinte forma:
ASAN_OPTIONS=allow_user_poisoning=0
Este software deve funcionar com a maioria dos sistemas baseados em UNIX (desde que as dependências de software necessárias estejam instaladas). O fluxo de trabalho do Github CI (discutido acima) garante que o software seja construído e executado de maneira razoável no Ubuntu Linux e MacOS. A principal plataforma de desenvolvimento do autor é o Fedora Linux. Portanto, o software também deve funcionar de maneira bastante confiável nessa plataforma.
