Using LLVM 16.0.6 Toolset

Red Hat Developer Tools 1

Installing and using LLVM 16.0.6 Toolset

Jacob Valdez

Red Hat Developer Group Documentation Team

Abstract

LLVM Toolset is a Red Hat offering for developers on the Red Hat Enterprise Linux (RHEL) operating system. Use this guide for an overview of LLVM Toolset, to learn how to invoke and use different versions of LLVM tools, and to find resources with more in-depth information.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. We are beginning with these four terms: master, slave, blacklist, and whitelist. Because of the enormity of this endeavor, these changes will be implemented gradually over several upcoming releases. For more details, see our CTO Chris Wright’s message.

Providing feedback on Red Hat documentation

We appreciate your feedback on our documentation. Let us know how we can improve it.

Submitting comments on specific passages

  1. View the documentation in the Multi-page HTML format and ensure that you see the Feedback button in the upper right corner after the page fully loads.
  2. Use your cursor to highlight the part of the text that you want to comment on.
  3. Click the Add Feedback button that appears near the highlighted text.
  4. Add your feedback and click Submit.

Submitting feedback through Jira (account required)

  1. Log in to the Jira website.
  2. Click Create in the top navigation bar
  3. Enter a descriptive title in the Summary field.
  4. Enter your suggestion for improvement in the Description field. Include links to the relevant parts of the documentation.
  5. Click Create at the bottom of the dialogue.

Chapter 1. LLVM Toolset

LLVM Toolset is a Red Hat offering for developers on Red Hat Enterprise Linux (RHEL). It provides the LLVM compiler infrastructure framework, the Clang compiler for the C and C++ languages, the LLDB debugger, and related tools for code analysis.

For Red Hat Enterprise Linux 8, LLVM Toolset is available as a module. LLVM Toolset is available as packages for Red Hat Enterprise Linux 9.

1.1. LLVM Toolset components

The following components are available as a part of LLVM Toolset:

NameVersionDescription

clang

16.0.6

An LLVM compiler front end for C and C++.

lldb

16.0.6

A C and C++ debugger using portions of LLVM.

compiler-rt

16.0.6

Runtime libraries for LLVM and Clang.

llvm

16.0.6

A collection of modular and reusable compiler and toolchain technologies.

libomp

16.0.6

A library for using Open MP API specification for parallel programming.

lld

16.0.6

An LLVM linker.

python-lit

16.0.6

A software testing tool for LLVM- and Clang-based test suites.

Note

The CMake build manager is not part of LLVM Toolset. On Red Hat Enterprise Linux 8, CMake is available in the system repository. On Red Hat Enterprise Linux 9, CMake is available in the system repository. For more information on how to install CMake, see Installing CMake on Red Hat Enterprise Linux.

1.2. LLVM Toolset compatibility

LLVM Toolset is available for Red Hat Enterprise Linux 8 and Red Hat Enterprise Linux 9 on the following architectures:

  • AMD and Intel 64-bit
  • 64-bit ARM
  • IBM Power Systems, Little Endian
  • 64-bit IBM Z

1.3. Installing LLVM Toolset

Complete the following steps to install LLVM Toolset including all development and debugging tools as well as dependent packages.

Prerequisites

  • All available Red Hat Enterprise Linux updates are installed.

Procedure

On Red Hat Enterprise Linux 8, install the llvm-toolset module by running:

# yum module install llvm-toolset
Important

This does not install the LLDB debugger or the python3-lit package on Red Hat Enterprise Linux 8. To install the LLDB debugger and the python3-lit package, run:

# yum install lldb python3-lit

On Red Hat Enterprise Linux 9, install the llvm-toolset package by running:

# dnf install llvm-toolset
Important

This does not install the LLDB debugger or the python3-lit package on Red Hat Enterprise Linux 9. To install the LLDB debugger and the python3-lit package, run:

# dnf install lldb python3-lit

1.4. Installing the CMake build manager

The CMake build manager is a tool that manages the build process of your source code independently from your compiler. CMake can generate a native build environment to compile source code, create libraries, generate wrappers, and build executable files.
Complete the following steps to install the CMake build manager.

Prerequisites

Procedure

To install CMake, run the following command:

  • On Red Hat Enterprise Linux 8:
# yum install cmake
  • On Red Hat Enterprise Linux 9:
# dnf install cmake

Additional resources

  • For more information on the CMake build manager, see the official CMake documentation overview About CMake.
  • For an introduction to using the CMake build manager, see:

1.5. Installing LLVM Toolset documentation

You can install documentation for LLVM Toolset on your local system.

Prerequisites

Procedure

To install the llvm-doc package, run the following command:

  • On Red Hat Enterprise Linux 8:

    # yum install llvm-doc

    You can find the documentation under the following path: /usr/share/doc/llvm/html/index.html.

  • On Red Hat Enterprise Linux 9:

    # dnf install llvm-doc

    You can find the documentation under the following path: /usr/share/doc/llvm/html/index.html.

1.6. Installing CMake documentation

You can install documentation for the CMake build manager on your local system.

Prerequisites

Procedure

To install the cmake-doc package, run the following command:

  • On Red Hat Enterprise Linux 8:

    # yum install cmake-doc

    You can find the documentation under the following path: /usr/share/doc/cmake/html/index.html.

  • On Red Hat Enterprise Linux 9:

    # dnf install cmake-doc

    You can find the documentation under the following path: /usr/share/doc/cmake/html/index.html.

1.7. Additional resources

Chapter 2. The Clang compiler

Clang is an LLVM compiler front end for the C-based languages C, C++, Objective C/C++, OpenCL, and Cuda.

LLVM Toolset is distributed with Clang 16.0.6.

2.1. Prerequisites

2.2. Compiling a source file

Use the Clang compiler to compile source files as well as assembly language source files. Clang creates an executable binary file as a result of compiling. To be able to debug your code, enable debug information by adding the -g flag to your Clang commands.

Note

To compile a C++ program, use clang++ instead of clang.

Procedure

To compile your program, run the following command:

  • On Red Hat Enterprise Linux 8:

    $ clang -o -g <binary_file> <source_file>
    • Replace <binary_file> with the desired name of your output file and <source_file> with the name of your source file.
  • On Red Hat Enterprise Linux 9:

    $ clang -o -g <binary_file> <source_file>
    • Replace <binary_file> with the desired name of your output file and <source_file> with the name of your source file.

2.3. Running a program

The Clang compiler creates an executable binary file as a result of compiling. Complete the following steps to execute this file and run your program.

Prerequisites

Procedure

To run your program, run in the directory containing the executable file:

$ ./<binary_file>
  • Replace <binary_file> with the name of your executable file.

2.4. Linking object files together

By linking object files together, you can compile only source files that contain changes instead of your entire project.
When you are working on a project that consists of several source files, use the Clang compiler to compile an object file for each of the source files. As a next step, link those object files together. Clang automatically generates an executable file containing your linked object files. After compilation, link your object files together again.

Note

To compile a C++ program, use clang++ instead of clang.

Procedure

  1. To compile a source file to an object file, run the following command:

    • On Red Hat Enterprise Linux 8:

      $ clang -o <object_file> -c <source_file>
      • Replace <object_file> with the desired name of your object file and <source_file> with the name of your source file.
    • On Red Hat Enterprise Linux 9:

      $ clang -o <object_file> -c <source_file>
      • Replace <object_file> with the desired name of your object file and <source_file> with the name of your source file.
  2. To link object files together, run the following command:

    • On Red Hat Enterprise Linux 8:

      $ clang -o <output_file> <object_file_0> <object_file_1>
      • Replace <output_file> with the desired name of your output file and <object_file> with the names of the object files you want to link.
    • On Red Hat Enterprise Linux 9:

      $ clang -o <output_file> <object_file_0> <object_file_1>
      • Replace <output_file> with the desired name of your output file and <object_file> with the names of the object files you want to link.
Important

At the moment, certain library features are statically linked into applications built with LLVM Toolset to support their execution on multiple versions of Red Hat Enterprise Linux. This creates a small security risk. Red Hat will issue a security erratum in case you need to rebuild your applications due to this risk.

Red Hat advises to not statically link your entire application.

2.5. Additional resources

Note

To compile a C++ program, use clang++ instead of clang.

  • On Red Hat Enterprise Linux 8:

    $ man clang
  • On Red Hat Enterprise Linux 9:

    $ man clang

Chapter 3. The LLDB debugger

The LLDB debugger is a command-line tool for debugging C and C++ programs. Use LLDB to inspect memory within the code being debugged, control the execution state of the code, and detect the execution of particular sections of code.

LLVM Toolset is distributed with LLDB 16.0.6.

3.1. Prerequisites

3.2. Starting a debugging session

Use LLDB to start an interactive debugging session.

Procedure

  • To run LLDB on a program you want to debug, use the following command:

    • On Red Hat Enterprise Linux 8:

      $ lldb <binary_file_name>
      • Replace <binary_file> with the name of your compiled program.

        You have started your LLDB debugging session in interactive mode. Your command-line terminal now displays the default prompt (lldb).

    • On Red Hat Enterprise Linux 9:

      $ lldb <binary_file>
      • Replace <binary_file> with the name of your compiled program.

        You have started your LLDB debugging session in interactive mode. Your command-line terminal now displays the default prompt (lldb).

  • To quit the debugging session and return to the shell prompt, run the following command:
(lldb) quit

3.3. Executing your program during a debugging session

Use LLDB to execute your program during your debugging session. The execution of your program stops when the first breakpoint is reached, when an error occurs, or when the program terminates.

Prerequisites

Procedure

  • To execute the program you are debugging, run:

    (lldb) run
  • To execute the program you are debugging using a specific argument, run:

    (lldb) run <argument>
    • Replace <argument> with the command-line argument you want to use.

3.4. Using breakpoints

Use breakpoints to pause the execution of your program at a set point in your source code.

Prerequisites

Procedure

  • To set a new breakpoint on a specific line, run the following command:

    (lldb) breakpoint set --file <source_file_name> --line <line_number>
    • Replace <source_file_name> with the name of your source file and <line_number> with the line number you want to set your breakpoint at.
  • To set a breakpoint on a specific function, run the following command:

    (lldb) breakpoint set --name <function_name>
    • Replace <function_name> with the name of the function you want to set your breakpoint at.
  • To display a list of currently set breakpoints, run the following command:

    (lldb) breakpoint list
  • To delete a breakpoint, run:

    (lldb) breakpoint clear -f <source_file_name> -l <line_number>
    • Replace <source_file_name> with the name of your source file and <line_number> with line number of the breakpoint you want to delete.
  • To resume the execution of your program after it reached a breakpoint, run:

    (lldb) continue
  • To skip a specific number of breakpoints, run the following command:

    (lldb) continue -i <breakpoints_to_skip>
    • Replace <breakpoints_to_skip> with the number of breakpoints you want to skip.

      Note

      To skip a loop, set the <breakpoints_to_skip> to match the loop iteration count.

3.5. Stepping through code

You can use LLDB to step through the code of your program to execute only one line of code after the line pointer.

Prerequisites

Procedure

  • To step through one line of code:

    1. Set your line pointer to the line you want to execute.
    2. Run the following command:

      (lldb) step
  • To step through a specific number of lines of code:

    1. Set your line pointer to the line you want to execute.
    2. Run the following command:

      (lldb) step -c <number>
      • Replace <number> with the number of lines you want to execute.

3.6. Listing source code

Before you execute the program you are debugging, the LLDB debugger automatically displays the first 10 lines of source code. Each time the execution of the program is stopped, LLDB displays the line of source code on which it stopped as well as its surrounding lines. You can use LLDB to manually trigger the display of source code during your debugging session.

Prerequisites

Procedure

  • To list the first 10 lines of the source code of the program you are debugging, run:

    (lldb) list
  • To display the source code from a specific line, run:

    (lldb) list <source_file_name>:<line_number>
    • Replace <source_file_name> with the name of your source file and <line_number> with the number of the line you want to display.

3.7. Displaying current program data

The LLDB debugger provides data on variables of any complexity, any valid expressions, and function call return values. You can use LLDB to display data relevant to the program state.

Prerequisites

Procedure

To display the current value of a certain variable, expression, or return value, run:

(lldb) print <data_name>
  • Replace <data_name> with data you want to display.

3.8. Additional resources

  • For more information on the LLDB debugger, see the official LLDB documentation LLDB Tutorial.
  • For a list of GDB commands and their LLDB equivalents, see the GDB to LLDB Command Map.

Chapter 4. Container images with LLVM Toolset on RHEL 8

On RHEL 8, you can build your own LLVM Toolset container images on top of Red Hat Universal Base Images (UBI) containers using Containerfiles.

4.1. Creating a container image of LLVM Toolset on RHEL 8

On RHEL 8, LLVM Toolset packages are part of the Red Hat Universal Base Images (UBIs) repositories. To keep the container image size small, install only individual packages instead of the entire LLVM Toolset.

Prerequisites

  • An existing Containerfile.
    For information on creating Containerfiles, see the Dockerfile reference page.

Procedure

  • Visit the Red Hat Container Catalog.
  • Select a UBI.
  • Click Get this image and follow the instructions.
  • To create a container image containing LLVM Toolset, add the following lines to your Containerfile:
FROM registry.access.redhat.com/ubi8/ubi:latest

RUN yum module install -y llvm-toolset
  • To create a container image containing an individual package only, add the following lines to your Containerfile:

    RUN yum install -y <package-name>
    • Replace <package-name> with the name of the package you want to install.

4.2. Additional resources

Chapter 5. Changes in LLVM Toolset

LLVM Toolset has been updated from version 15.0.7 to 16.0.6 on RHEL 8 and RHEL 9. Notable changes include:

  • Improvements to optimization
  • Support for new CPU extensions
  • Improved support for new C++ versions

Notable backwards incompatible changes include:

  • Clang’s default C++ standard is now gnu++17 instead of gnu++14.
  • The -Wimplicit-function-declaration, -Wimplicit-int and -Wincompatible-function-pointer-types options now default to error for C code. This might affect the behavior of configure scripts.

By default, Clang 16 uses the libstdc++ library version 13 and binutils 2.40 provided by GCC Toolset 13.

Legal Notice

Copyright © 2023 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.