diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore index d7a67220bea..8d4fddacc23 100644 --- a/doc/org.eclipse.cdt.doc.user/.gitignore +++ b/doc/org.eclipse.cdt.doc.user/.gitignore @@ -2,4 +2,5 @@ /concepts/docinfo-footer.htm /concepts/docinfo-header.htm /getting_started/ +/llvm/ /example/ diff --git a/doc/org.eclipse.cdt.doc.user/build.properties b/doc/org.eclipse.cdt.doc.user/build.properties index 349217b3538..a654ba75c60 100644 --- a/doc/org.eclipse.cdt.doc.user/build.properties +++ b/doc/org.eclipse.cdt.doc.user/build.properties @@ -26,11 +26,13 @@ bin.includes = about.html,\ helpadoc.css,\ font-awesome/,\ images/,\ + llvm/,\ plugin.properties,\ plugin.xml,\ 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 dc5d78ea802..3e9227402d8 100644 --- a/doc/org.eclipse.cdt.doc.user/plugin.xml +++ b/doc/org.eclipse.cdt.doc.user/plugin.xml @@ -14,6 +14,10 @@ file="toc.xml" primary="true"> + + diff --git a/doc/org.eclipse.cdt.doc.user/src/.gitignore b/doc/org.eclipse.cdt.doc.user/src/.gitignore new file mode 100644 index 00000000000..9273b7d9522 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/.gitignore @@ -0,0 +1 @@ +.asciidoctorconfig.adoc diff --git a/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc b/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc new file mode 100644 index 00000000000..667d2bef7b9 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc @@ -0,0 +1,44 @@ +//// +Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation +This program and the accompanying materials +are made available under the terms of the Eclipse Public License 2.0 +which accompanies this distribution, and is available at +https://www.eclipse.org/legal/epl-2.0/ + +SPDX-License-Identifier: EPL-2.0 +//// + +// pull in shared headers, footers, etc +:docinfo: shared + +// support image rendering and table of contents within GitHub +ifdef::env-github[] +:imagesdir: ../../images +:toc: +:toc-placement!: +endif::[] + +// enable support for button, menu and keyboard macros +:experimental: + +// Until ENDOFHEADER the content must match adoc-headers.txt for consistency, +// this is checked by the build in do_generate_asciidoc.sh, which also ensures +// that the checked in html is up to date. +// do_generate_asciidoc.sh can also be used to apply this header to all the +// adoc files. +// ENDOFHEADER + +== 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. + +http://www.llvm.org[LLVM] is a rather 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: +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 new file mode 100644 index 00000000000..50ad9bece6e --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc @@ -0,0 +1,53 @@ +//// +Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation +This program and the accompanying materials +are made available under the terms of the Eclipse Public License 2.0 +which accompanies this distribution, and is available at +https://www.eclipse.org/legal/epl-2.0/ + +SPDX-License-Identifier: EPL-2.0 +//// + +// pull in shared headers, footers, etc +:docinfo: shared + +// support image rendering and table of contents within GitHub +ifdef::env-github[] +:imagesdir: ../../images +:toc: +:toc-placement!: +endif::[] + +// enable support for button, menu and keyboard macros +:experimental: + +// Until ENDOFHEADER the content must match adoc-headers.txt for consistency, +// this is checked by the build in do_generate_asciidoc.sh, which also ensures +// that the checked in html is up to date. +// do_generate_asciidoc.sh can also be used to apply this header to all the +// adoc files. +// ENDOFHEADER + +== 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. + +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}. + +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. 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 new file mode 100644 index 00000000000..7c8b365e386 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc @@ -0,0 +1,64 @@ +//// +Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation +This program and the accompanying materials +are made available under the terms of the Eclipse Public License 2.0 +which accompanies this distribution, and is available at +https://www.eclipse.org/legal/epl-2.0/ + +SPDX-License-Identifier: EPL-2.0 +//// + +// pull in shared headers, footers, etc +:docinfo: shared + +// support image rendering and table of contents within GitHub +ifdef::env-github[] +:imagesdir: ../../images +:toc: +:toc-placement!: +endif::[] + +// enable support for button, menu and keyboard macros +:experimental: + +// Until ENDOFHEADER the content must match adoc-headers.txt for consistency, +// this is checked by the build in do_generate_asciidoc.sh, which also ensures +// that the checked in html is up to date. +// do_generate_asciidoc.sh can also be used to apply this header to all the +// adoc files. +// ENDOFHEADER + +== LLVM Specific Information + +=== Project types + +==== [#executables]#Executables# + +At the moment the executables built with the default settings of a 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 +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 +running them from Eclipse doesn't work at the moment). + +===== Compiling to LLVM bitcode instead of native binary + +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. + +==== [#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 +cannot be used with gcc unless compiled to object code first. These +libraries can naturally be used when working with the LLVM toolchain and +on the other hand llvm-ld can use libraries that are object code. diff --git a/doc/org.eclipse.cdt.doc.user/src/llvm/user_manual.adoc b/doc/org.eclipse.cdt.doc.user/src/llvm/user_manual.adoc new file mode 100644 index 00000000000..356df27f3c5 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/llvm/user_manual.adoc @@ -0,0 +1,39 @@ +//// +Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation +This program and the accompanying materials +are made available under the terms of the Eclipse Public License 2.0 +which accompanies this distribution, and is available at +https://www.eclipse.org/legal/epl-2.0/ + +SPDX-License-Identifier: EPL-2.0 +//// + +// pull in shared headers, footers, etc +:docinfo: shared + +// support image rendering and table of contents within GitHub +ifdef::env-github[] +:imagesdir: ../../images +:toc: +:toc-placement!: +endif::[] + +// enable support for button, menu and keyboard macros +:experimental: + +// Until ENDOFHEADER the content must match adoc-headers.txt for consistency, +// this is checked by the build in do_generate_asciidoc.sh, which also ensures +// that the checked in html is up to date. +// do_generate_asciidoc.sh can also be used to apply this header to all the +// adoc files. +// ENDOFHEADER + +== LLVM with Clang/GCC for Eclipse CDT + +This guide is intended for the users of the LLVM with Clang/GCC for +Eclipse CDT plugin. It describes the initial configuration, general +information and some special cases about the plugin. + +* xref:general.adoc[General information] +* xref:initial_configuration.adoc[Initial configuration] +* xref:llvm_specific.adoc[LLVM specific information and options] diff --git a/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml b/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml new file mode 100644 index 00000000000..67d31d1b220 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/toc_LLVM.xml @@ -0,0 +1,9 @@ + + + + + + + + + diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties index 28288d4a0b6..408f8827dc8 100644 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties +++ b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties @@ -8,8 +8,6 @@ bin.includes = plugin.xml,\ about.ini,\ about.mappings,\ about.properties,\ - cdt_logo_icon32.png,\ - help/ + cdt_logo_icon32.png src.includes = patches/,\ - help/,\ about.html diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/general.html b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/general.html deleted file mode 100644 index 2a461924401..00000000000 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/general.html +++ /dev/null @@ -1,13 +0,0 @@ - - - - -General information - - -

General information

-

LLVM with Clang/GCC for Eclipse CDT plug-in provides LLVM toolchain with Clang or llvm-gcc compiler to compile C/C++ programs.

-

LLVM is a rather modern toolchain that supports the compilation of C/C++ 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: Clang/Clang++/llvm-gcc/llvm-g++ (C/C++ compilers), llvm-ld (linker), llvm-ar (archiver), llvm-as (assembler), llc (static compiler) and lli (JIT/Interpreter). - - \ No newline at end of file diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/initial_configuration.html b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/initial_configuration.html deleted file mode 100644 index 3b14c092593..00000000000 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/initial_configuration.html +++ /dev/null @@ -1,14 +0,0 @@ - - - - -Initial configuration - - -

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.

-

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 C++.

-

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 C++ Library in order to compile C++ programs by adding the path in LLVM Preferences or appending it to LD_LIBRARY_PATH system environment variable.

- - \ No newline at end of file diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/llvm_specific.html b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/llvm_specific.html deleted file mode 100644 index bc127ab3990..00000000000 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/llvm_specific.html +++ /dev/null @@ -1,17 +0,0 @@ - - - - -LLVM Specific Information - - -

LLVM Specific Information

-

Project types

-

Executables

-

At the moment the executables built with the default settings of a 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 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 running them from Eclipse doesn't work at the moment).

-

Compiling to LLVM bitcode instead of native binary

-

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/C++ 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.

-

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 cannot be used with gcc unless compiled to object code first. These libraries can naturally be used when working with the LLVM toolchain and on the other hand llvm-ld can use libraries that are object code.

- - \ No newline at end of file diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/toc.xml b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/toc.xml deleted file mode 100644 index cd02aa7ae74..00000000000 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/toc.xml +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/user_manual.html b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/user_manual.html deleted file mode 100644 index 6f6ddc9241f..00000000000 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/help/user_manual.html +++ /dev/null @@ -1,17 +0,0 @@ - - - - -User manual - LLVM with Clang/GCC for Eclipse CDT - - -

LLVM with Clang/GCC for Eclipse CDT

-

This guide is intended for the users of the LLVM with Clang/GCC for Eclipse CDT plugin. It describes the initial configuration, general information and some special cases about the plugin.

- - - \ No newline at end of file diff --git a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml index fbefb078f99..8a58bb8e1f6 100644 --- a/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml +++ b/llvm/org.eclipse.cdt.managedbuilder.llvm.ui/plugin.xml @@ -5483,13 +5483,6 @@ Contributors: - - - -