clang_libraries_companion
v0.2.0
Este repositorio contiene todos los ejemplos de código que están asociados con el siguiente mazo de diapositivas:
El mazo de diapositivas está disponible para descargar en:
El repositorio está organizado de la siguiente manera:
Cada ejemplo de código o grupo de ejemplos de código está estructurado como un proyecto CMake separado. Esto permite a los usuarios experimentar con un ejemplo de código individual sin tener que construir todos los ejemplos de código. Por conveniencia, se proporcionan dos archivos CMAKELISTS.TXT que crean todos sus proyectos subordinados. Todos los proyectos se pueden construir utilizando un script de compilación proporcionado (que invoca estos dos superbuilds de CMake).
Este repositorio emplea un flujo de trabajo CI basado en acciones de GitHub. Cada vez que se presiona una nueva confirmación, los ejemplos de código en el repositorio se crean y se ejecutan como una prueba básica de cordura. Este flujo de trabajo CI sirve como un ejemplo para mostrar cómo los paquetes LLVM/Clang Ubuntu APT que proporcionan el proyecto LLVM (en https://apt.llvm.org/) se pueden usar en corredores Linux Hostux Hosted Github. El flujo de trabajo de CI actualmente se desarrolla para algunas combinaciones de las siguientes:
Los ejemplos de código tienen las siguientes dependencias de software:
Estas dependencias deben instalarse antes de construir los ejemplos de código.
Si la biblioteca estándar C ++ no admite el formato STD ::, una versión personalizada de la biblioteca FMT se puede instalar automáticamente (como parte del proceso de compilación) para proporcionar este soporte. (Esta versión personalizada de la biblioteca FMT proporciona un encabezado de la biblioteca estándar llamado "formato" y coloca algunas declaraciones clave en el espacio de nombres STD en ese encabezado). La biblioteca estándar C ++ incluida con la versión 13 y superior de GCC tiene soporte para el formato STD ::.
Por conveniencia, se proporciona un DockerFile para construir un entorno contenedorizado que incluya todas las dependencias de software necesarias. Se proporciona más información sobre este Dockerfile en una sección posterior.
Los ejemplos de código emplean un proceso de construcción basado en Cmake. Cada ejemplo de código o grupo de ejemplos relacionados está estructurado como un proyecto CMake separado. Por conveniencia, se proporciona un script para construir todos los ejemplos de código en un solo paso.
Algunos de los ejemplos de código requieren std :: format (introducido en C ++ 20). Si la implementación de la biblioteca estándar C ++ que se utiliza no admite el formato STD ::, una versión personalizada de la biblioteca FMT se puede instalar automáticamente (como parte del proceso de compilación) para proporcionar este soporte.
Para construir todos los ejemplos de código (y opcionalmente ejecutar todas las demostraciones asociadas), haga lo siguiente:
Inicialice el entorno de modo que las dependencias de software necesarias (por ejemplo, ejecutables, encabezados o bibliotecas) se encuentren con éxito en el tiempo de compilación. Por lo general, este paso solo se requiere si algunas de las dependencias del software se instalan en ubicaciones donde el proceso de compilación no las encontraría normalmente. Cuando se requiere este paso, puede parecerse a lo siguiente:
# 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
Establezca el directorio de trabajo actual en el directorio de nivel superior del árbol de trabajo del repositorio Git clonado.
Invoca el script de compilación con las opciones apropiadas. Nominalmente, el guión se invoca de la siguiente manera:
./build --defaults
Si la biblioteca estándar C ++ que se utiliza es compatible con el formato STD ::, la opción "--No-FMT" se puede agregar a la invocación del script de compilación anterior (para que no se utilice la versión personalizada de la biblioteca FMT). Es decir, se puede usar el siguiente comando:
./build --defaults --no-fmt
El script de compilación admite numerosas opciones. Para obtener información de uso detallada, invoque el script con la opción "-h" o "--help". Los argumentos de línea de comandos se procesan en orden de izquierda a derecha. Entonces, en el caso de que se establece una configuración en más de una opción de línea de comandos, la configuración desde la opción más derecha entra en vigencia.
Si lo desea, ejecute los scripts de demostración (como prueba de cordura básica) con el comando:
./build --demo
La salida del proceso de compilación se coloca en los directorios:
La salida para cada proyecto CMake se coloca en un directorio que tiene el mismo nombre que ese proyecto. Por ejemplo, la salida de compilación para el proyecto llamado ciclomático_complexidad de los ejemplos de la cubierta deslizante se coloca en el directorio:
slides/examples/tmp_build/cyclomatic_complexity
La mayoría de los proyectos tienen un script de demostración (llamado "demostración" o con un nombre que contiene "demostración"). Por ejemplo, para ejecutar el script de demostración para el proyecto Cyclomatic_Complexity, use el comando:
slides/examples/tmp_build/cyclomatic_complexity/demo
Se proporciona un DockerFile que puede usarse para crear un contenedor de Podman/Docker con todas las dependencias de software necesarias para construir y ejecutar los ejemplos de código en este repositorio. Las instrucciones se dan a continuación sobre cómo usar este entorno contenedorizado. Aunque estas instrucciones usan (Rootless) Podman, los programas de Podman y Docker tienen interfaces de línea de comandos casi idénticas. Por lo tanto, debería ser posible sustituir "Docker" por "Podman" en las instrucciones.
Deje que $ top_dir denote el directorio de nivel superior del árbol de trabajo del repositorio de git clonado (es decir, el directorio que contiene el archivo llamado ReadMe.md que está leyendo actualmente). Tenga en cuenta que $ top_dir debería ser una ruta absoluta.
Establezca el directorio de trabajo en el directorio de nivel superior del árbol de trabajo utilizando el comando:
cd $TOP_DIR
Construya el contenedor usando el comando:
podman build --tag cl-demo - < podman/Dockerfile
Cree una instancia temporal del contenedor y ejecute un shell de bash en el contenedor usando el 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
Tenga en cuenta que las opciones "-Cap-Add" y "--security-opt" pueden no ser necesarias.
Si no desea que se elimine el contenedor después de que salga el shell bash, omita la opción "--RM".
Proceda a construir y ejecutar los scripts de demostración como se describe en detalle en una sección anterior. Por ejemplo, uno podría invocar el siguiente comando desde el shell bash que se ejecuta en el contenedor:
./build --defaults
A veces, el uso del desinfectante de direcciones (ASAN) puede ser problemático, debido, por ejemplo, a las peculiaridades en la plataforma en la que se ejecuta el código. El comportamiento de tiempo de ejecución de ASAN se puede controlar a través de la variable de entorno ASAN_OPTIONS, cuyo valor es una lista separada por colon de pares de valor clave (por ejemplo, "Verbosidad = 1: Detect_leaks = 0").
En algunas plataformas, se ha observado que algunas de las bibliotecas utilizadas por los ejemplos de código tienen fugas de memoria. Si ASAN se queja de que algunas bibliotecas tienen fugas de memoria, la detección de fugas de memoria se puede deshabilitar agregando "Detect_leaks = 0" a la lista de opciones de ASAN en la variable de entorno ASAN_OPTIONTions. Por ejemplo, ASAN_OPTION se puede configurar de la siguiente manera:
ASAN_OPTIONS=detect_leaks=0
Parece que el envenenamiento de la memoria de los usuarios a veces puede dar lugar a falsos positivos de ASAN (a saber, los errores de uso de uso posterior), dependiendo de cómo se construyó LLVM/Clang. Esto probablemente se deba a las inconsistencias en cómo se maneja el envenenamiento de los usuarios en las bibliotecas LLVM/Clang y la aplicación utilizando estas bibliotecas. Si se encuentra este problema, el envenenamiento del usuario se puede deshabilitar agregando "tampion_user_poisoning = 0" a la lista de opciones de ASAN en la variable de entorno ASAN_OPTIONS. Por ejemplo, ASAN_OPTION se puede configurar de la siguiente manera:
ASAN_OPTIONS=allow_user_poisoning=0
Este software debe funcionar con la mayoría de los sistemas basados en UNIX (siempre que se instalen las dependencias de software necesarias). El flujo de trabajo GitHub CI (discutido anteriormente) asegura que el software debe construir y ejecutar razonablemente de manera confiable en Ubuntu Linux y MacOS. La principal plataforma de desarrollo del autor es Fedora Linux. Por lo tanto, el software también debería funcionar de manera bastante confiable en esta plataforma.
