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

@@ -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.

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

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,\

doc/org.eclipse.cdt.doc.user/plugin.xml

@@ -14,10 +14,6 @@
             file="toc.xml"
             primary="true">
       </toc>
-      <toc
-            file="toc_LLVM.xml"
-            primary="true">
-      </toc>
       <index path="index"/>
    </extension>
 

doc/org.eclipse.cdt.doc.user/setting_up_eclipse_cdt/src/eclipse.xml

@@ -246,7 +246,7 @@
         <para>For Linux, select "Linux GCC"</para>
       </listitem>
       <listitem>
-        <para>For Mac OS X, select "MacOSX GCC"</para>
+        <para>For macOS, select "macOS GCC"</para>
       </listitem>
       <listitem>
         <para>Do not use "Cross GCC"! Unfortunately this option may be

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]

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).

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`.

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

doc/org.eclipse.cdt.doc.user/toc_LLVM.xml

@@ -1,9 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<toc label="LLVM plug-in for Eclipse CDT">
-	<topic label="User manual" href="llvm/user_manual.htm">
-		<topic label="General information about the plugin" href="llvm/general.htm"/>
-		<topic label="Initial configuration" href="llvm/initial_configuration.htm"/>
-		<topic label="LLVM specific information and options" href="llvm/llvm_specific.htm">
-		</topic>
-	</topic>
-</toc>

doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml

@@ -20,5 +20,11 @@
               <topic label="Building a project" href="getting_started/cdt_w_build.htm"/>
               <topic label="Debugging projects" href="getting_started/cdt_w_debug.htm"/>
               <topic label="Importing C/C++ source files into Eclipse" href="getting_started/cdt_w_existing_code.htm"/>
+              <topic label="LLVM with Clang/GCC for Eclipse CDT" href="llvm/user_manual.htm">
+                      <topic label="General information about the plugin" href="llvm/general.htm"/>
+                      <topic label="Initial configuration" href="llvm/initial_configuration.htm"/>
+                      <topic label="LLVM specific information and options" href="llvm/llvm_specific.htm">
+              </topic>
+	</topic>
           </topic>
 </toc>

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)
 

llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml

@@ -851,7 +851,7 @@ Contributors:
          <option
                category="llvm.c_cpp.compiler.category.optimization"
                command="-emit-llvm"
-               defaultValue="true"
+               defaultValue="false"
                id="llvm.c_cpp.compiler.option.optimization.emit-llvm"
                name="%Option.Llvm.Clang.EmitLlvm.name"
                tip="%Option.Llvm.Clang.EmitLlvm.tip"