Compilation Example
Hello World Example
In this section, we will show to compile source code with compiler and compiler flags. To get started, let’s start with a simple hello world example we have available in C and C++ as shown below
#include <stdio.h>
int main() {
printf("Hello, World in C\n");
return 0;
}
#include <iostream>
int main() {
std::cout << "Hello, World in C++" << std::endl;
return 0;
}
Shown below is an example buildspec file that will compile the above source code with the gcc compiler.
The compilers section is used to specify the compiler to use that is selected via the name property which applies
a regular expression to search for compiler. The compilers are defined in buildtest configuration file see Defining Compilers
for more details.
buildspecs:
hello_world_c_cpp:
type: script
executor: generic.local.bash
description: Hello world compilation in C and C++
compilers:
name: ['builtin_gcc']
run: |
$BUILDTEST_CC hello.c -o hello_c
$BUILDTEST_CXX hello.cpp -o hello_cpp
./hello_c
./hello_cpp
Buildtest will define environment variables like BUILDTEST_CC and BUILDTEST_CXX that point to the C and C++
compiler wrapper for the selected compiler.
Let’s try to run the code and inspect the test output and test file.
buildtest build -b tutorials/compilation/hello_world_compilation.yml
$ buildtest build -b tutorials/compilation/hello_world_compilation.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-25534835-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2024/09/05 15:37:40 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 2.1 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.9.19 │
│ Configuration File: /tmp/tmpr88132k2/config.yml │
│ Test Directory: /tmp/tmpr88132k2/var/tests │
│ Report File: /tmp/tmpr88132k2/var/report.json │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/stable/ ║
║ tutorials/compilation/hello_world_compilation.yml ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 1 ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/stable/tutorials/compilation/hello_world_compilation.yml: VALID
Total builder objects created: 1
Builders by type=script
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ ┃ ┃ ┃ descrip ┃ buildspe ┃
┃ builder ┃ type ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ tion ┃ cs ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ hello_wo │ script │ generic. │ builtin_ │ None │ None │ Hello │ /home/do │
│ rld_c_cp │ │ local.ba │ gcc │ │ │ world │ cs/check │
│ p/3e1cbb │ │ sh │ │ │ │ compila │ outs/rea │
│ 4e │ │ │ │ │ │ tion in │ dthedocs │
│ │ │ │ │ │ │ C and │ .org/use │
│ │ │ │ │ │ │ C++ │ r_builds │
│ │ │ │ │ │ │ │ /buildte │
│ │ │ │ │ │ │ │ st/check │
│ │ │ │ │ │ │ │ outs/sta │
│ │ │ │ │ │ │ │ ble/tuto │
│ │ │ │ │ │ │ │ rials/co │
│ │ │ │ │ │ │ │ mpilatio │
│ │ │ │ │ │ │ │ n/hello_ │
│ │ │ │ │ │ │ │ world_co │
│ │ │ │ │ │ │ │ mpilatio │
│ │ │ │ │ │ │ │ n.yml │
└──────────┴────────┴──────────┴──────────┴───────┴───────┴─────────┴──────────┘
──────────────────────────────── Building Test ─────────────────────────────────
hello_world_c_cpp/3e1cbb4e: Creating Test Directory: /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
hello_world_c_cpp/3e1cbb4e does not have any dependencies adding test to queue
Builders Eligible to Run
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ hello_world_c_cpp/3e1cbb4e │
└────────────────────────────┘
hello_world_c_cpp/3e1cbb4e: Current Working Directory : /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/stage
hello_world_c_cpp/3e1cbb4e: Running Test via command: bash hello_world_c_cpp_build.sh
hello_world_c_cpp/3e1cbb4e: Test completed in 0.991007 seconds with returncode: 0
hello_world_c_cpp/3e1cbb4e: Writing output file - /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp.out
hello_world_c_cpp/3e1cbb4e: Writing error file - /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp.err
Test Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ builder ┃ executor ┃ status ┃ returncode ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ hello_world_c_cpp/3e1cb │ generic.local.bash │ PASS │ 0 │ 0.991 │
│ b4e │ │ │ │ │
└─────────────────────────┴────────────────────┴────────┴────────────┴─────────┘
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Adding 1 test results to report file: /tmp/tmpr88132k2/var/report.json
Writing Logfile to /tmp/tmpr88132k2/var/logs/buildtest_5stpf5tq.log
$ buildtest inspect query -o -t hello_world_c_cpp
──────────── hello_world_c_cpp/3e1cbb4e-26a9-458e-b3a7-6540d9f6c3c6 ────────────
Executor: generic.local.bash
Description: Hello world compilation in C and C++
State: PASS
Returncode: 0
Runtime: 0.991007 sec
Starttime: 2024/09/05 15:37:40
Endtime: 2024/09/05 15:37:41
Command: bash hello_world_c_cpp_build.sh
Test Script: /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp.sh
Build Script: /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp_build.sh
Output File: /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp.out
Error File: /tmp/tmpr88132k2/var/tests/generic.local.bash/hello_world_compilation/hello_world_c_cpp/3e1cbb4e/hello_world_c_cpp.err
Log File: /tmp/tmpr88132k2/var/logs/buildtest_5stpf5tq.log
──────────────────────────────── Output File: ─────────────────────────────────
Hello, World in C
Hello, World in C++
────────────────────────────────────────────────────────────────────────────────
───────────────────────────────── Test File: ──────────────────────────────────
#!/usr/bin/bash
BUILDTEST_CC="gcc"
BUILDTEST_CXX="g++"
BUILDTEST_FC="gfortran"
BUILDTEST_CFLAGS=
BUILDTEST_CXXFLAGS=
BUILDTEST_FFLAGS=
BUILDTEST_CPPFLAGS=
BUILDTEST_LDFLAGS=
# Content of run section
$BUILDTEST_CC hello.c -o hello_c
$BUILDTEST_CXX hello.cpp -o hello_cpp
./hello_c
./hello_cpp
────────────────────────────────────────────────────────────────────────────────
Please note that the compiler definition for builtin_gcc is a canonical name to reference to system GNU
compiler that is set to /usr/bin/gcc, /usr/bin/g++. The compiler details can be extracted from the configuration
file via buildtest config compilers list command. Shown below is the YAML output of the compiler details.
$ buildtest config compilers list --yaml
gcc:
builtin_gcc:
cc: gcc
cxx: g++
fc: gfortran
STREAM Benchmark Example
In this next section, we will run the STREAM memory benchmark. In order to run this example,
we will need to download the source code and compile the source code. We will use the curl command to download the source code. The
default section is used to specify default compiler settings for compiler, this may include compiler options and environment variables.
The cflags option is responsible for setting C compiler flags which is set to environment variable BUILDTEST_CFLAGS that we can access in
the run section. The env section is used to set environment variables that are used in the run section.
buildspecs:
stream_openmp_c:
executor: generic.local.bash
type: script
description: "STREAM Microbenchmark C Test with OpenMP"
tags: ["benchmark"]
compilers:
name: ['(builtin_gcc)']
default:
gcc:
cflags: -fopenmp -O2
env:
OMP_NUM_THREADS: 8
run: |
curl https://www.cs.virginia.edu/stream/FTP/Code/stream.c -o stream.c
$BUILDTEST_CC $BUILDTEST_CFLAGS stream.c -o stream
./stream
buildtest build -b tutorials/compilation/stream.yml
$ buildtest build -b tutorials/compilation/stream.yml
╭───────────────────────────── buildtest summary ──────────────────────────────╮
│ │
│ User: docs │
│ Hostname: build-25534835-project-280831-buildtest │
│ Platform: Linux │
│ Current Time: 2024/09/05 15:37:43 │
│ buildtest path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ buildtest version: 2.1 │
│ python path: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ python version: 3.9.19 │
│ Configuration File: /tmp/tmpr88132k2/config.yml │
│ Test Directory: /tmp/tmpr88132k2/var/tests │
│ Report File: /tmp/tmpr88132k2/var/report.json │
│ Command: /home/docs/checkouts/readthedocs.org/user_builds/buildte │
│ │
╰──────────────────────────────────────────────────────────────────────────────╯
─────────────────────────── Discovering Buildspecs ────────────────────────────
Discovered buildspecs
╔══════════════════════════════════════════════════════════════════════════════╗
║ buildspec ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ /home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/stable/ ║
║ tutorials/compilation/stream.yml ║
╟──────────────────────────────────────────────────────────────────────────────╢
║ Total: 1 ║
╚══════════════════════════════════════════════════════════════════════════════╝
Total Discovered Buildspecs: 1
Total Excluded Buildspecs: 0
Detected Buildspecs after exclusion: 1
────────────────────────────── Parsing Buildspecs ──────────────────────────────
Valid Buildspecs: 1
Invalid Buildspecs: 0
/home/docs/checkouts/readthedocs.org/user_builds/buildtest/checkouts/stable/tutorials/compilation/stream.yml: VALID
Total builder objects created: 1
Builders by type=script
┏━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━┳━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┓
┃ ┃ ┃ ┃ ┃ ┃ ┃ descrip ┃ buildspe ┃
┃ builder ┃ type ┃ executor ┃ compiler ┃ nodes ┃ procs ┃ tion ┃ cs ┃
┡━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━╇━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━┩
│ stream_o │ script │ generic. │ builtin_ │ None │ None │ STREAM │ /home/do │
│ penmp_c/ │ │ local.ba │ gcc │ │ │ Microbe │ cs/check │
│ 31f423c4 │ │ sh │ │ │ │ nchmark │ outs/rea │
│ │ │ │ │ │ │ C Test │ dthedocs │
│ │ │ │ │ │ │ with │ .org/use │
│ │ │ │ │ │ │ OpenMP │ r_builds │
│ │ │ │ │ │ │ │ /buildte │
│ │ │ │ │ │ │ │ st/check │
│ │ │ │ │ │ │ │ outs/sta │
│ │ │ │ │ │ │ │ ble/tuto │
│ │ │ │ │ │ │ │ rials/co │
│ │ │ │ │ │ │ │ mpilatio │
│ │ │ │ │ │ │ │ n/stream │
│ │ │ │ │ │ │ │ .yml │
└──────────┴────────┴──────────┴──────────┴───────┴───────┴─────────┴──────────┘
──────────────────────────────── Building Test ─────────────────────────────────
stream_openmp_c/31f423c4: Creating Test Directory: /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4
──────────────────────────────── Running Tests ─────────────────────────────────
Spawning 1 processes for processing builders
───────────────────────────────── Iteration 1 ──────────────────────────────────
stream_openmp_c/31f423c4 does not have any dependencies adding test to queue
Builders Eligible to Run
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Builder ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ stream_openmp_c/31f423c4 │
└──────────────────────────┘
stream_openmp_c/31f423c4: Current Working Directory : /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stage
stream_openmp_c/31f423c4: Running Test via command: bash stream_openmp_c_build.sh
stream_openmp_c/31f423c4: Test completed in 1.319269 seconds with returncode: 0
stream_openmp_c/31f423c4: Writing output file - /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c.out
stream_openmp_c/31f423c4: Writing error file - /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c.err
Test Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┓
┃ builder ┃ executor ┃ status ┃ returncode ┃ runtime ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━┩
│ stream_openmp_c/31f423c │ generic.local.bash │ PASS │ 0 │ 1.319 │
│ 4 │ │ │ │ │
└─────────────────────────┴────────────────────┴────────┴────────────┴─────────┘
Passed Tests: 1/1 Percentage: 100.000%
Failed Tests: 0/1 Percentage: 0.000%
Adding 1 test results to report file: /tmp/tmpr88132k2/var/report.json
Writing Logfile to /tmp/tmpr88132k2/var/logs/buildtest_gsid5d_6.log
$ buildtest inspect query -o -t stream_openmp_c
───────────── stream_openmp_c/31f423c4-1666-41a4-a3eb-d033841175d2 ─────────────
Executor: generic.local.bash
Description: STREAM Microbenchmark C Test with OpenMP
State: PASS
Returncode: 0
Runtime: 1.319269 sec
Starttime: 2024/09/05 15:37:43
Endtime: 2024/09/05 15:37:44
Command: bash stream_openmp_c_build.sh
Test Script: /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c.sh
Build Script: /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c_build.sh
Output File: /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c.out
Error File: /tmp/tmpr88132k2/var/tests/generic.local.bash/stream/stream_openmp_c/31f423c4/stream_openmp_c.err
Log File: /tmp/tmpr88132k2/var/logs/buildtest_gsid5d_6.log
──────────────────────────────── Output File: ─────────────────────────────────
-------------------------------------------------------------
STREAM version $Revision: 5.10 $
-------------------------------------------------------------
This system uses 8 bytes per array element.
-------------------------------------------------------------
Array size = 10000000 (elements), Offset = 0 (elements)
Memory per array = 76.3 MiB (= 0.1 GiB).
Total memory required = 228.9 MiB (= 0.2 GiB).
Each kernel will be executed 10 times.
The *best* time for each kernel (excluding the first iteration)
will be used to compute the reported bandwidth.
-------------------------------------------------------------
Number of Threads requested = 8
Number of Threads counted = 8
-------------------------------------------------------------
Your clock granularity/precision appears to be 1 microseconds.
Each test below will take on the order of 11413 microseconds.
(= 11413 clock ticks)
Increase the size of the arrays if this shows that
you are not getting at least 20 clock ticks per test.
-------------------------------------------------------------
WARNING -- The above is only a rough guideline.
For best results, please be sure you know the
precision of your system timer.
-------------------------------------------------------------
Function Best Rate MB/s Avg time Min time Max time
Copy: 12442.8 0.013869 0.012859 0.014187
Scale: 10341.9 0.015682 0.015471 0.016024
Add: 12373.0 0.019628 0.019397 0.019851
Triad: 11738.7 0.020591 0.020445 0.020933
-------------------------------------------------------------
Solution Validates: avg error less than 1.000000e-13 on all three arrays
-------------------------------------------------------------
────────────────────────────────────────────────────────────────────────────────
───────────────────────────────── Test File: ──────────────────────────────────
#!/usr/bin/bash
BUILDTEST_CC="gcc"
BUILDTEST_CXX="g++"
BUILDTEST_FC="gfortran"
BUILDTEST_CFLAGS="-fopenmp -O2"
BUILDTEST_CXXFLAGS=
BUILDTEST_FFLAGS=
BUILDTEST_CPPFLAGS=
BUILDTEST_LDFLAGS=
export OMP_NUM_THREADS="8"
# Content of run section
curl https://www.cs.virginia.edu/stream/FTP/Code/stream.c -o stream.c
$BUILDTEST_CC $BUILDTEST_CFLAGS stream.c -o stream
./stream
────────────────────────────────────────────────────────────────────────────────