clang_libraries_companion
v0.2.0
ที่เก็บนี้มีตัวอย่างรหัสทั้งหมดที่เกี่ยวข้องกับเด็คสไลด์ต่อไปนี้:
เด็คสไลด์สามารถดาวน์โหลดได้ที่:
ที่เก็บมีการจัดระเบียบดังนี้:
แต่ละตัวอย่างรหัสหรือกลุ่มของตัวอย่างรหัสมีโครงสร้างเป็นโครงการ CMake แยกต่างหาก สิ่งนี้ช่วยให้ผู้ใช้สามารถทดสอบด้วยตัวอย่างรหัสแต่ละตัวโดยไม่ต้องสร้างตัวอย่างโค้ดทั้งหมด เพื่อความสะดวกไฟล์ cmakelists.txt สองไฟล์มีให้เพื่อสร้างโครงการรองทั้งหมดของพวกเขา โครงการทั้งหมดสามารถสร้างขึ้นได้โดยใช้สคริปต์สร้างที่ให้มา (ซึ่งเรียกใช้ CMake Superbuilds ทั้งสองนี้)
ที่เก็บนี้ใช้เวิร์กโฟลว์ CI ตามการกระทำของ GitHub ทุกครั้งที่มีการผลักดันการประชุมใหม่ตัวอย่างรหัสในที่เก็บจะถูกสร้างและดำเนินการเพื่อทดสอบความมีสติพื้นฐาน เวิร์กโฟลว์ CI นี้ทำหน้าที่เป็นตัวอย่างเพื่อแสดงว่าแพ็คเกจ LLVM/Clang Ubuntu APT ที่จัดทำโดยโครงการ LLVM (ที่ https://apt.llvm.org/) สามารถใช้งานได้ ขณะนี้เวิร์กโฟลว์ CI สร้างขึ้นสำหรับชุดค่าผสมของสิ่งต่อไปนี้:
ตัวอย่างโค้ดมีการพึ่งพาซอฟต์แวร์ต่อไปนี้:
การพึ่งพาเหล่านี้จะต้องติดตั้งก่อนที่จะสร้างตัวอย่างรหัส
หากไลบรารีมาตรฐาน C ++ ไม่รองรับรูปแบบ std :: รูปแบบเวอร์ชันที่กำหนดเองของไลบรารี FMT สามารถติดตั้งโดยอัตโนมัติ (เป็นส่วนหนึ่งของกระบวนการสร้าง) เพื่อให้การสนับสนุนนี้ (ไลบรารี FMT เวอร์ชันที่กำหนดเองนี้มีส่วนหัวไลบรารีมาตรฐานที่เรียกว่า "รูปแบบ" และวางประกาศคีย์สองสามข้อในเนมสเปซ STD ในส่วนหัวนั้น) ไลบรารีมาตรฐาน C ++ ที่รวมอยู่ในเวอร์ชัน 13 และสูงกว่าของ GCC ได้รองรับรูปแบบ STD ::
เพื่อความสะดวกมี DockerFile จัดเตรียมไว้เพื่อสร้างสภาพแวดล้อมคอนเทนเนอร์ซึ่งรวมถึงการพึ่งพาซอฟต์แวร์ที่จำเป็นทั้งหมด ข้อมูลเพิ่มเติมเกี่ยวกับ DockerFile นี้มีให้ในส่วนต่อมา
ตัวอย่างรหัสใช้กระบวนการสร้างที่ใช้ CMAKE แต่ละตัวอย่างรหัสหรือกลุ่มของตัวอย่างที่เกี่ยวข้องมีโครงสร้างเป็นโครงการ CMake แยกต่างหาก เพื่อความสะดวกสคริปต์มีไว้สำหรับการสร้างตัวอย่างรหัสทั้งหมดในขั้นตอนเดียว
ตัวอย่างรหัสบางส่วนต้องใช้รูปแบบ std :: (แนะนำใน C ++ 20) หากการใช้งานไลบรารีมาตรฐาน C ++ ที่ใช้ไม่รองรับรูปแบบ STD :: สามารถติดตั้งไลบรารี FMT เวอร์ชันที่กำหนดเองได้โดยอัตโนมัติ (เป็นส่วนหนึ่งของกระบวนการสร้าง) เพื่อให้การสนับสนุนนี้
ในการสร้างตัวอย่างรหัสทั้งหมด (และเรียกใช้การสาธิตทั้งหมดที่เกี่ยวข้องทั้งหมด) ให้ทำสิ่งต่อไปนี้:
เริ่มต้นสภาพแวดล้อมเช่นการพึ่งพาซอฟต์แวร์ที่จำเป็น (เช่น executables, ส่วนหัวหรือห้องสมุด) จะพบได้สำเร็จในเวลาที่สร้าง โดยทั่วไปแล้วขั้นตอนนี้จะต้องใช้เฉพาะเมื่อมีการติดตั้งซอฟต์แวร์การพึ่งพาบางส่วนในสถานที่ที่กระบวนการสร้างโดยปกติจะไม่พบ เมื่อต้องการขั้นตอนนี้มันอาจมีลักษณะดังต่อไปนี้:
# 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
ตั้งค่าไดเรกทอรีการทำงานปัจจุบันเป็นไดเรกทอรีระดับบนสุดของต้นไม้ทำงานของที่เก็บ GIT ที่โคลน
เรียกใช้สคริปต์บิลด์ด้วยตัวเลือกที่เหมาะสม ในนามสคริปต์จะถูกเรียกใช้ดังนี้:
./build --defaults
หากไลบรารีมาตรฐาน C ++ ที่ใช้เกิดขึ้นเพื่อรองรับรูปแบบ std :: ตัวเลือก "-no-fmt" สามารถเพิ่มลงในการเรียกใช้สคริปต์บิลด์ด้านบน (เพื่อไม่ใช้เวอร์ชันที่กำหนดเองของไลบรารี FMT) นั่นคือคำสั่งต่อไปนี้สามารถใช้:
./build --defaults --no-fmt
บิลด์สคริปต์รองรับตัวเลือกมากมาย สำหรับข้อมูลการใช้งานโดยละเอียดให้เรียกใช้สคริปต์ด้วยตัวเลือก "-H" หรือ "-HELP" อาร์กิวเมนต์บรรทัดคำสั่งจะถูกประมวลผลตามลำดับจากซ้ายไปขวา ดังนั้นในกรณีที่การตั้งค่าถูกสร้างขึ้นโดยตัวเลือกบรรทัดคำสั่งมากกว่าหนึ่งตัวเลือกการตั้งค่าจากตัวเลือกขวาสุดจะมีผล
หากต้องการให้เรียกใช้สคริปต์สาธิต (เป็นการทดสอบสติพื้นฐาน) ด้วยคำสั่ง:
./build --demo
เอาต์พุตของกระบวนการสร้างถูกวางไว้ในไดเรกทอรี:
เอาต์พุตสำหรับแต่ละโครงการ CMake ถูกวางไว้ในไดเรกทอรีที่มีชื่อเดียวกับโครงการนั้น ตัวอย่างเช่นการสร้างเอาต์พุตสำหรับโครงการที่เรียกว่า cyclomatic_complexity จากตัวอย่างสไลด์ดาดฟ้าถูกวางไว้ในไดเรกทอรี:
slides/examples/tmp_build/cyclomatic_complexity
โครงการส่วนใหญ่มีสคริปต์ตัวอย่าง (เรียกว่า "สาธิต" หรือมีชื่อที่มี "สาธิต") ตัวอย่างเช่นในการเรียกใช้สคริปต์ตัวอย่างสำหรับโครงการ cyclomatic_complexity ให้ใช้คำสั่ง:
slides/examples/tmp_build/cyclomatic_complexity/demo
DockerFile มีให้ที่สามารถใช้ในการสร้างคอนเทนเนอร์ Podman/Docker ด้วยซอฟต์แวร์ที่จำเป็นทั้งหมดสำหรับการสร้างและเรียกใช้ตัวอย่างรหัสในที่เก็บนี้ คำแนะนำจะได้รับด้านล่างเกี่ยวกับวิธีการใช้สภาพแวดล้อมคอนเทนเนอร์นี้ แม้ว่าคำแนะนำเหล่านี้จะใช้ Podman (Rootless) แต่โปรแกรม Podman และ Docker มีอินเทอร์เฟซบรรทัดคำสั่งเกือบเหมือนกัน ดังนั้นควรเป็นไปได้ที่จะแทนที่ "นักเทียบท่า" สำหรับ "Podman" ในคำแนะนำ
ให้ $ top_dir แสดงไดเรกทอรีระดับบนสุดของต้นไม้ทำงานของที่เก็บ Git ที่โคลน (เช่นไดเรกทอรีที่มีไฟล์ชื่อ readme.md ซึ่งคุณกำลังอ่านอยู่) โปรดทราบว่า $ top_dir ควรเป็นเส้นทางที่แน่นอน
ตั้งค่าไดเรกทอรีการทำงานเป็นไดเรกทอรีระดับบนสุดของต้นไม้ทำงานโดยใช้คำสั่ง:
cd $TOP_DIR
สร้างคอนเทนเนอร์โดยใช้คำสั่ง:
podman build --tag cl-demo - < podman/Dockerfile
สร้างอินสแตนซ์ชั่วคราวของคอนเทนเนอร์และเรียกใช้เชลล์ทุบตีในคอนเทนเนอร์โดยใช้คำสั่ง:
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
โปรดทราบว่าอาจไม่จำเป็นต้องใช้ตัวเลือก "-CAP-ADD" และ "-Security-Opt"
หากคุณไม่ต้องการให้ตู้คอนเทนเนอร์ถูกลบหลังจากออกจากเชลล์ทุบตีให้ละเว้นตัวเลือก "--rm"
ดำเนินการต่อเพื่อสร้างและเรียกใช้สคริปต์สาธิตตามที่อธิบายไว้ในรายละเอียดในส่วนก่อนหน้า ตัวอย่างเช่นหนึ่งอาจเรียกใช้คำสั่งต่อไปนี้จาก bash shell ที่ทำงานในคอนเทนเนอร์:
./build --defaults
บางครั้งการใช้ที่อยู่ของ sanitizer (ASAN) อาจเป็นปัญหาเช่นเนื่องจากการแก้ปัญหาในแพลตฟอร์มที่รหัสกำลังรัน พฤติกรรมรันไทม์ของ ASAN สามารถควบคุมได้ผ่านตัวแปรสภาพแวดล้อม ASAN_OPTIONS ซึ่งมีค่าเป็นรายการที่แยกจากลำไส้ใหญ่ของคู่คีย์-ค่า (เช่น "verbosity = 1: detect_leaks = 0")
ในบางแพลตฟอร์มห้องสมุดบางส่วนที่ใช้โดยตัวอย่างรหัสได้รับการสังเกตว่ามีการรั่วไหลของหน่วยความจำ หาก ASAN บ่นเกี่ยวกับไลบรารีบางแห่งที่มีการรั่วไหลของหน่วยความจำการตรวจจับการรั่วไหลของหน่วยความจำสามารถปิดใช้งานได้โดยการเพิ่ม "DETECT_LEAKS = 0" ในรายการตัวเลือก ASAN ในตัวแปรสภาพแวดล้อม ASAN_OPTIONS ตัวอย่างเช่น ASAN_OPTIONS สามารถตั้งค่าได้ดังนี้:
ASAN_OPTIONS=detect_leaks=0
ปรากฏว่าบางครั้งผู้ใช้เป็นพิษของหน่วยความจำอาจส่งผลให้เกิดผลบวกปลอมจาก ASAN (คือข้อผิดพลาดในการใช้งานที่เป็นพิษ) ขึ้นอยู่กับว่า LLVM/Clang ถูกสร้างขึ้นอย่างไร นี่อาจเป็นเพราะความไม่สอดคล้องกันในการจัดการพิษของผู้ใช้ในไลบรารี LLVM/Clang และแอปพลิเคชันที่ใช้ไลบรารีเหล่านี้ หากพบปัญหานี้การเป็นพิษของผู้ใช้สามารถปิดใช้งานได้โดยการเพิ่ม "ALDE_USER_POISONING = 0" ในรายการตัวเลือก ASAN ในตัวแปรสภาพแวดล้อม ASAN_OPTIONS ตัวอย่างเช่น ASAN_OPTIONS สามารถตั้งค่าได้ดังนี้:
ASAN_OPTIONS=allow_user_poisoning=0
ซอฟต์แวร์นี้ควรทำงานกับระบบที่ใช้ UNIX ส่วนใหญ่ (โดยมีเงื่อนไขว่ามีการติดตั้งซอฟต์แวร์ที่จำเป็น) เวิร์กโฟลว์ GitHub CI (กล่าวถึงข้างต้น) ทำให้มั่นใจได้ว่าซอฟต์แวร์ควรสร้างและเรียกใช้อย่างสมเหตุสมผลใน Ubuntu Linux และ MacOS แพลตฟอร์มการพัฒนาหลักของผู้เขียนคือ Fedora Linux ดังนั้นซอฟต์แวร์ควรทำงานได้อย่างน่าเชื่อถือบนแพลตฟอร์มนี้เช่นกัน
