From cce2876d6b561e65d1e6125045abd8aa802ecdd2 Mon Sep 17 00:00:00 2001 From: John Dallaway Date: Fri, 15 Aug 2025 14:37:07 +0100 Subject: [PATCH] Update and integrate LLVM documentation The LLVM MBS toolchain plugin help is integrated into the CDT Getting Started guide. The 'Emit LLVM IR' tool option is documented and disabled by default. Instances of "MacOS X" in MBS toolchain display strings are replaced with "macOS". --- FAQ/README.md | 11 ++++--- .../plugin.properties | 12 +++---- doc/org.eclipse.cdt.doc.user/build.properties | 1 - doc/org.eclipse.cdt.doc.user/plugin.xml | 4 --- .../setting_up_eclipse_cdt/src/eclipse.xml | 2 +- .../src/getting_started/index_mbs.adoc | 2 ++ .../src/llvm/general.adoc | 8 ++--- .../src/llvm/initial_configuration.adoc | 33 ++++++++----------- .../src/llvm/llvm_specific.adoc | 28 +++++++--------- doc/org.eclipse.cdt.doc.user/toc_LLVM.xml | 9 ----- .../topics_Getting_Started.xml | 6 ++++ .../plugin.properties | 13 ++++---- .../plugin.xml | 2 +- 13 files changed, 59 insertions(+), 72 deletions(-) delete mode 100644 doc/org.eclipse.cdt.doc.user/toc_LLVM.xml diff --git a/FAQ/README.md b/FAQ/README.md index f20b7cb5d3b..829e85b9b82 100644 --- a/FAQ/README.md +++ b/FAQ/README.md @@ -2140,8 +2140,9 @@ For macOS Sierra (10.12), there seems to be additional problems with GDB that might make it unusable, see the [GDB bug report](https://sourceware.org/bugzilla/show_bug.cgi?id=20266). -GDB does not support local macOS application debugging on Apple silicon -(AArch64) at present. It is necessary to use the LLDB debugger instead. +> [!NOTE] +> GDB does not support local macOS application debugging on Apple silicon +> (AArch64) at present. It is necessary to use the LLDB debugger instead. #### How do I get the LLDB debugger? @@ -2209,7 +2210,7 @@ with #### How do I install the LLDB debugger integration? -1. Go to Help \> Install new Software +1. Go to Help > Install new Software 2. Select the CDT update site (9.1 or greater) 3. Under **CDT Optional Features**, select **C/C++ LLDB Debugger Integration** @@ -2359,8 +2360,8 @@ setvbuf(stderr, NULL, _IONBF, 0); CDT does not come with a compiler, so if you do not have one you will need to install one. Follows are options available to you: -- macOS: Install Xcode from the App Store or from Apple Developer web -site. +- macOS: Install the _Xcode Command Line Tools_ from the App Store or +from Apple Developer web site. - Linux: If not already installed, it should be available in your distribution's package system on your installation CDs. diff --git a/build/org.eclipse.cdt.managedbuilder.gnu.ui/plugin.properties b/build/org.eclipse.cdt.managedbuilder.gnu.ui/plugin.properties index 7a12df92941..35e83637a2c 100644 --- a/build/org.eclipse.cdt.managedbuilder.gnu.ui/plugin.properties +++ b/build/org.eclipse.cdt.managedbuilder.gnu.ui/plugin.properties @@ -28,9 +28,9 @@ TargetName.gnu.lib=Gnu Static Library TargetName.cygw.exe=Cygwin Executable TargetName.cygw.so=Cygwin DLL TargetName.cygw.lib=Cygwin Library -TargetName.macosx.exe=MacOS X Executable -TargetName.macosx.so=MacOS X Shared Library -TargetName.macosx.lib=MacOS X Static Library +TargetName.macosx.exe=macOS Executable +TargetName.macosx.so=macOS Shared Library +TargetName.macosx.lib=macOS Static Library TargetName.solaris.exe=Solaris Gnu Executable TargetName.solaris.so=Solaris Gnu Shared Library TargetName.solaris.lib=Solaris Gnu Static Library @@ -57,7 +57,7 @@ ToolChainName.Dbg=GCC Tool Chain ToolChainName.Linux=Linux GCC ToolChainName.Cygwin=Cygwin GCC ToolChainName.MinGW=MinGW GCC -ToolChainName.Macosx=MacOSX GCC +ToolChainName.Macosx=macOS GCC ToolChainName.Solaris=Solaris GCC # Generic platform names @@ -96,8 +96,8 @@ ToolName.linker.mingw.gnu.c=MinGW C Linker ToolName.linker.mingw.gnu.cpp=MinGW C++ Linker # Mach-O tool names -ToolName.linker.macosx.c = MacOS X C Linker -ToolName.linker.macosx.cpp = MacOS X C++ Linker +ToolName.linker.macosx.c = macOS C Linker +ToolName.linker.macosx.cpp = macOS C++ Linker #Solaris tool names ToolName.compiler.solaris.c = Solaris C Compiler diff --git a/doc/org.eclipse.cdt.doc.user/build.properties b/doc/org.eclipse.cdt.doc.user/build.properties index a654ba75c60..aee29b82fa8 100644 --- a/doc/org.eclipse.cdt.doc.user/build.properties +++ b/doc/org.eclipse.cdt.doc.user/build.properties @@ -32,7 +32,6 @@ bin.includes = about.html,\ reference/,\ tasks/,\ toc.xml,\ - toc_LLVM.xml,\ topics_Concepts.xml,\ topics_Getting_Started.xml,\ topics_Reference.xml,\ diff --git a/doc/org.eclipse.cdt.doc.user/plugin.xml b/doc/org.eclipse.cdt.doc.user/plugin.xml index 3e9227402d8..dc5d78ea802 100644 --- a/doc/org.eclipse.cdt.doc.user/plugin.xml +++ b/doc/org.eclipse.cdt.doc.user/plugin.xml @@ -14,10 +14,6 @@ file="toc.xml" primary="true"> - - diff --git a/doc/org.eclipse.cdt.doc.user/setting_up_eclipse_cdt/src/eclipse.xml b/doc/org.eclipse.cdt.doc.user/setting_up_eclipse_cdt/src/eclipse.xml index 281d7bf6a56..57fc21d0031 100644 --- a/doc/org.eclipse.cdt.doc.user/setting_up_eclipse_cdt/src/eclipse.xml +++ b/doc/org.eclipse.cdt.doc.user/setting_up_eclipse_cdt/src/eclipse.xml @@ -246,7 +246,7 @@ For Linux, select "Linux GCC" - For Mac OS X, select "MacOSX GCC" + For macOS, select "macOS GCC" Do not use "Cross GCC"! Unfortunately this option may be diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/index_mbs.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/index_mbs.adoc index ca73a3abba0..88e3180216b 100644 --- a/doc/org.eclipse.cdt.doc.user/src/getting_started/index_mbs.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/index_mbs.adoc @@ -43,3 +43,5 @@ xref:cdt_w_build.adoc[Building a project] xref:cdt_w_debug.adoc[Debugging a project] xref:cdt_w_existing_code.adoc[Importing your C/{cpp} source files into Eclipse] + +xref:../llvm/user_manual.adoc[LLVM with Clang/GCC for Eclipse CDT] diff --git a/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc b/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc index 667d2bef7b9..2b51ed1bfa9 100644 --- a/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc @@ -30,15 +30,15 @@ endif::[] == General information -LLVM with Clang/GCC for Eclipse CDT plug-in provides LLVM toolchain with -Clang or llvm-gcc compiler to compile C/(cpp} programs. +The LLVM with Clang/GCC for Eclipse CDT plug-in integrates an LLVM toolchain using +the Clang or llvm-gcc compiler with the CDT managed build system to compile C/(cpp} programs. -http://www.llvm.org[LLVM] is a rather modern toolchain that supports the +http://www.llvm.org[LLVM] is a modern toolchain that supports the compilation of C/(cpp} code (among others) to LLVM virtual machine's _bitcode_, which in turn can be compiled to each platform's native binary. -The plug-in includes the following tools from the LLVM toolchain: +The plug-in integrates the following tools from the LLVM toolchain: Clang/Clang{plus}{plus}/llvm-gcc/llvm-g{plus}{plus} (C/(cpp} compilers), llvm-ld (linker), llvm-ar (archiver), llvm-as (assembler), llc (static compiler) and lli (JIT/Interpreter). diff --git a/doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc b/doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc index 50ad9bece6e..25f2cc91c6b 100644 --- a/doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc @@ -30,24 +30,19 @@ endif::[] == Initial configuration -When you launch an Eclipse workspace with LLVM plug-in for the first -time, you may need to set paths to LLVM binaries, headers and libraries. -This is done in Eclipse by navigating to Window -> Preferences -> LLVM. -Set LLVM installation folder to point where your LLVM binaries are, -include directory to point where your Clang includes are and library -path to the directory where your LLVM libraries reside. +On Linux and macOS hosts, the LLVM toolchain will typically be installed via the package +management tool provided by the Linux distribution or as part of the +_Xcode Command Line Tools_ and will be located on the system `PATH`. +If your LLVM toolchain is not on the system `PATH` when launching the Eclipse Workbench, +you may need to add the location of your LLVM binaries to the `PATH` environment variable +within Eclipse. This is done by navigating to Window -> Preferences -> +C/{cpp} -> Build -> Environment. Select the `PATH` environment variable and then edit its +value to point where your LLVM binaries are located. -If your paths in Preferences and LLVM are correctly set and the plug-in -is able to find your LLVM binaries, you should have the option to use -"LLVM with Clang (Linux/MacOSX/Windows)" toolchain and "LLVM with GCC -(Linux/MacOSX/Windows) toolchain". The toolchains are available in -project types of 'executable', 'static library' and 'dynamic library' in -both C and {cpp}. +If your `PATH` environment variable is set correctly, you should see the +_LLVM with Clang_ and _LLVM with GCC_ toolchains available for selection within the +CDT project wizard for managed build projects. The toolchains are available for both +C and {cpp} projects. -An alternative way is to set the LLVM binary path to PATH system -environment variable. - -You may also have to include the path to -Standard {cpp} Library in order to compile {cpp} programs by adding the -path in LLVM Preferences or appending it to LD_LIBRARY_PATH system -environment variable. +NOTE: Clang is automatically detected when installed on a Microsoft Windows host using +the MSYS2 package manager. It is not necessary to modify the `PATH`. diff --git a/doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc b/doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc index 7c8b365e386..0d0463d6647 100644 --- a/doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc @@ -32,30 +32,26 @@ endif::[] === Project types -==== [#executables]#Executables# +==== Executables -At the moment the executables built with the default settings of a LLVM +The executables built with the default settings of an LLVM with Clang project are native binaries and can be run and debugged as -such. However LLVM does also support compiling programs to LLVM bitcode, -which in turn can be run with lli, which is the LLVM toolchain's -interpreter/JIT compiler. Unfortunately programs run with lli can not be +such. However LLVM does also support building programs to LLVM bitcode, +which in turn can be run with `lli`, which is the LLVM toolchain's +interpreter/JIT compiler. Unfortunately programs run with `lli` can not be efficiently debugged, since the only (usable) debugging information that you can get from them is the backtrace. You can, however, compile the -bitcode versions of your programs, if you will (TODO: even though +bitcode versions of your programs, if you wish (TODO: even though running them from Eclipse doesn't work at the moment). -===== Compiling to LLVM bitcode instead of native binary +===== Compiling to LLVM bitcode instead of object code -You can compile your programs to LLVM bitcode instead of native binaries -by unchecking the "Create native binary (-native)" checkbox in your -project's properties in Properties → C/{cpp} Build → Settings → LLVM -Linker → General LLVM options. After this Eclipse will not give the --native flag to llvm-ld, so the product of linking is just linked -bitcode files (.bc) and a Bash script file with the name of the wanted -executable. The Bash script will simply run the compiled LLVM bitcode -file with lli. +C/{cpp} source files are compiled to native object code by default. You can compile +your source files to LLVM bitcode instead of object code by checking the _Emit LLVM IR_ +checkbox in the Project Properties dialog on the Properties -> C/{cpp} Build -> +Settings -> LLVM Clang -> Optimization page. -==== [#libraries]#Shared and static libraries# +==== Shared and static libraries The shared and static libraries generated with LLVM plugin are (TODO: for now) only LLVM bitcode files linked into one file and therefore diff --git a/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml b/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml deleted file mode 100644 index 67d31d1b220..00000000000 --- a/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml b/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml index 23a117ae3fc..c26bd1a0e3b 100644 --- a/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml +++ b/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml @@ -20,5 +20,11 @@ + + + + + + diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.properties b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.properties index 14430668fd7..ea6f784d0b2 100644 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.properties +++ b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.properties @@ -1,5 +1,5 @@ ############################################################################### -# Copyright (c) 2010 Nokia Siemens Networks Oyj, Finland. +# Copyright (c) 2010, 2025 Nokia Siemens Networks Oyj and others # # This program and the accompanying materials # are made available under the terms of the Eclipse Public License 2.0 @@ -9,7 +9,8 @@ # SPDX-License-Identifier: EPL-2.0 # # Contributors: -# Nokia Siemens Networks Oyj, initial LLVM support as an add-on to CDT. +# Nokia Siemens Networks Oyj, initial LLVM support as an add-on to CDT +# John Dallaway, add option for clang '-emit-llvm' (#1277) ############################################################################### # plugin names @@ -25,20 +26,20 @@ ToolChainName.llvm=LLVM ToolChainName.llvm.with.linker=LLVM with C/C++ Linker ToolChainName.llvm.with.static.compiler=LLVM with static compiler ToolChainName.llvm.static.compiler.linux=LLVM with static compiler (Linux) -ToolChainName.llvm.static.compiler.macosx=LLVM with static compiler (MacOSX) +ToolChainName.llvm.static.compiler.macosx=LLVM with static compiler (macOS) ToolChainName.llvm.static.compiler.win32=LLVM with static compiler (Windows) ToolChainName.llvm.jit=LLVM with JIT/Interpreter ToolChainName.llvm.jit.linux=LLVM with JIT/Interpreter (Linux) -ToolChainName.llvm.jit.macosx=LLVM with JIT/Interpreter (MacOSX) +ToolChainName.llvm.jit.macosx=LLVM with JIT/Interpreter (macOS) ToolChainName.llvm.jit.win32=LLVM with JIT/Interpreter (Windows) ToolChainName.llvm.clang=LLVM with Clang ToolChainName.llvm.clang.win32.mingw=LLVM with Clang (Windows) (MinGW)\u0020 ToolChainName.llvm.clang.win32.cygwin=LLVM with Clang (Windows) (Cygwin) ToolChainName.llvm.linux=LLVM with Clang (Linux) -ToolChainName.llvm.macosx=LLVM with Clang (MacOSX) +ToolChainName.llvm.macosx=LLVM with Clang (macOS) ToolChainName.llvm.gnu=LLVM with GCC ToolChainName.llvm.gnu.linux=LLVM with GCC (Linux) -ToolChainName.llvm.gnu.macosx=LLVM with GCC (MacOSX) +ToolChainName.llvm.gnu.macosx=LLVM with GCC (macOS) ToolChainName.llvm.gnu.win32.cygwin=LLVM with GCC (Windows) (Cygwin) ToolChainName.llvm.gnu.win32.mingw=LLVM with GCC (Windows) (MinGW) diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml index 8a58bb8e1f6..f57096a7029 100644 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml +++ b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml @@ -851,7 +851,7 @@ Contributors: