Skip to content

Commit 59e80dd

Browse files
jld01jld01
committed
Convert LLVM managed build help pages to AsciiDoc
1 parent 2a38be3 commit 59e80dd

File tree

16 files changed

+218
-80
lines changed

16 files changed

+218
-80
lines changed

‎doc/org.eclipse.cdt.doc.user/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,5 @@
22
/concepts/docinfo-footer.htm
33
/concepts/docinfo-header.htm
44
/getting_started/
5+
/llvm/
56
/example/

‎doc/org.eclipse.cdt.doc.user/build.properties‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,13 @@ bin.includes = about.html,\
2626
helpadoc.css,\
2727
font-awesome/,\
2828
images/,\
29+
llvm/,\
2930
plugin.properties,\
3031
plugin.xml,\
3132
reference/,\
3233
tasks/,\
3334
toc.xml,\
35+
toc_LLVM.xml,\
3436
topics_Concepts.xml,\
3537
topics_Getting_Started.xml,\
3638
topics_Reference.xml,\

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

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,10 @@
1414
file="toc.xml"
1515
primary="true">
1616
</toc>
17+
<toc
18+
file="toc_LLVM.xml"
19+
primary="true">
20+
</toc>
1721
<index path="index"/>
1822
</extension>
1923

‎doc/org.eclipse.cdt.doc.user/src/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.asciidoctorconfig.adoc

‎doc/org.eclipse.cdt.doc.user/src/llvm/general.adoc‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
////
2+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
3+
This program and the accompanying materials
4+
are made available under the terms of the Eclipse Public License 2.0
5+
which accompanies this distribution, and is available at
6+
https://www.eclipse.org/legal/epl-2.0/
7+
8+
SPDX-License-Identifier: EPL-2.0
9+
////
10+
11+
// pull in shared headers, footers, etc
12+
:docinfo: shared
13+
14+
// support image rendering and table of contents within GitHub
15+
ifdef::env-github[]
16+
:imagesdir: ../../images
17+
:toc:
18+
:toc-placement!:
19+
endif::[]
20+
21+
// enable support for button, menu and keyboard macros
22+
:experimental:
23+
24+
// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
25+
// this is checked by the build in do_generate_asciidoc.sh, which also ensures
26+
// that the checked in html is up to date.
27+
// do_generate_asciidoc.sh can also be used to apply this header to all the
28+
// adoc files.
29+
// ENDOFHEADER
30+
31+
== General information
32+
33+
LLVM with Clang/GCC for Eclipse CDT plug-in provides LLVM toolchain with
34+
Clang or llvm-gcc compiler to compile C/(cpp} programs.
35+
36+
http://www.llvm.org[LLVM] is a rather modern toolchain that supports the
37+
compilation of C/(cpp} code (among others) to LLVM virtual machine's
38+
_bitcode_, which in turn can be compiled to each platform's native
39+
binary.
40+
41+
The plug-in includes the following tools from the LLVM toolchain:
42+
Clang/Clang{plus}{plus}/llvm-gcc/llvm-g{plus}{plus} (C/(cpp} compilers), llvm-ld (linker),
43+
llvm-ar (archiver), llvm-as (assembler), llc (static compiler) and lli
44+
(JIT/Interpreter).

‎doc/org.eclipse.cdt.doc.user/src/llvm/initial_configuration.adoc‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
////
2+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
3+
This program and the accompanying materials
4+
are made available under the terms of the Eclipse Public License 2.0
5+
which accompanies this distribution, and is available at
6+
https://www.eclipse.org/legal/epl-2.0/
7+
8+
SPDX-License-Identifier: EPL-2.0
9+
////
10+
11+
// pull in shared headers, footers, etc
12+
:docinfo: shared
13+
14+
// support image rendering and table of contents within GitHub
15+
ifdef::env-github[]
16+
:imagesdir: ../../images
17+
:toc:
18+
:toc-placement!:
19+
endif::[]
20+
21+
// enable support for button, menu and keyboard macros
22+
:experimental:
23+
24+
// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
25+
// this is checked by the build in do_generate_asciidoc.sh, which also ensures
26+
// that the checked in html is up to date.
27+
// do_generate_asciidoc.sh can also be used to apply this header to all the
28+
// adoc files.
29+
// ENDOFHEADER
30+
31+
== Initial configuration
32+
33+
When you launch an Eclipse workspace with LLVM plug-in for the first
34+
time, you may need to set paths to LLVM binaries, headers and libraries.
35+
This is done in Eclipse by navigating to Window -> Preferences -> LLVM.
36+
Set LLVM installation folder to point where your LLVM binaries are,
37+
include directory to point where your Clang includes are and library
38+
path to the directory where your LLVM libraries reside.
39+
40+
If your paths in Preferences and LLVM are correctly set and the plug-in
41+
is able to find your LLVM binaries, you should have the option to use
42+
"LLVM with Clang (Linux/MacOSX/Windows)" toolchain and "LLVM with GCC
43+
(Linux/MacOSX/Windows) toolchain". The toolchains are available in
44+
project types of 'executable', 'static library' and 'dynamic library' in
45+
both C and {cpp}.
46+
47+
An alternative way is to set the LLVM binary path to PATH system
48+
environment variable.
49+
50+
You may also have to include the path to
51+
Standard {cpp} Library in order to compile {cpp} programs by adding the
52+
path in LLVM Preferences or appending it to LD_LIBRARY_PATH system
53+
environment variable.

‎doc/org.eclipse.cdt.doc.user/src/llvm/llvm_specific.adoc‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
////
2+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
3+
This program and the accompanying materials
4+
are made available under the terms of the Eclipse Public License 2.0
5+
which accompanies this distribution, and is available at
6+
https://www.eclipse.org/legal/epl-2.0/
7+
8+
SPDX-License-Identifier: EPL-2.0
9+
////
10+
11+
// pull in shared headers, footers, etc
12+
:docinfo: shared
13+
14+
// support image rendering and table of contents within GitHub
15+
ifdef::env-github[]
16+
:imagesdir: ../../images
17+
:toc:
18+
:toc-placement!:
19+
endif::[]
20+
21+
// enable support for button, menu and keyboard macros
22+
:experimental:
23+
24+
// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
25+
// this is checked by the build in do_generate_asciidoc.sh, which also ensures
26+
// that the checked in html is up to date.
27+
// do_generate_asciidoc.sh can also be used to apply this header to all the
28+
// adoc files.
29+
// ENDOFHEADER
30+
31+
== LLVM Specific Information
32+
33+
=== Project types
34+
35+
==== [#executables]#Executables#
36+
37+
At the moment the executables built with the default settings of a LLVM
38+
with Clang project are native binaries and can be run and debugged as
39+
such. However LLVM does also support compiling programs to LLVM bitcode,
40+
which in turn can be run with lli, which is the LLVM toolchain's
41+
interpreter/JIT compiler. Unfortunately programs run with lli can not be
42+
efficiently debugged, since the only (usable) debugging information that
43+
you can get from them is the backtrace. You can, however, compile the
44+
bitcode versions of your programs, if you will (TODO: even though
45+
running them from Eclipse doesn't work at the moment).
46+
47+
===== Compiling to LLVM bitcode instead of native binary
48+
49+
You can compile your programs to LLVM bitcode instead of native binaries
50+
by unchecking the "Create native binary (-native)" checkbox in your
51+
project's properties in Properties → C/{cpp} Build → Settings → LLVM
52+
Linker → General LLVM options. After this Eclipse will not give the
53+
-native flag to llvm-ld, so the product of linking is just linked
54+
bitcode files (.bc) and a Bash script file with the name of the wanted
55+
executable. The Bash script will simply run the compiled LLVM bitcode
56+
file with lli.
57+
58+
==== [#libraries]#Shared and static libraries#
59+
60+
The shared and static libraries generated with LLVM plugin are (TODO:
61+
for now) only LLVM bitcode files linked into one file and therefore
62+
cannot be used with gcc unless compiled to object code first. These
63+
libraries can naturally be used when working with the LLVM toolchain and
64+
on the other hand llvm-ld can use libraries that are object code.

‎doc/org.eclipse.cdt.doc.user/src/llvm/user_manual.adoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
////
2+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
3+
This program and the accompanying materials
4+
are made available under the terms of the Eclipse Public License 2.0
5+
which accompanies this distribution, and is available at
6+
https://www.eclipse.org/legal/epl-2.0/
7+
8+
SPDX-License-Identifier: EPL-2.0
9+
////
10+
11+
// pull in shared headers, footers, etc
12+
:docinfo: shared
13+
14+
// support image rendering and table of contents within GitHub
15+
ifdef::env-github[]
16+
:imagesdir: ../../images
17+
:toc:
18+
:toc-placement!:
19+
endif::[]
20+
21+
// enable support for button, menu and keyboard macros
22+
:experimental:
23+
24+
// Until ENDOFHEADER the content must match adoc-headers.txt for consistency,
25+
// this is checked by the build in do_generate_asciidoc.sh, which also ensures
26+
// that the checked in html is up to date.
27+
// do_generate_asciidoc.sh can also be used to apply this header to all the
28+
// adoc files.
29+
// ENDOFHEADER
30+
31+
== LLVM with Clang/GCC for Eclipse CDT
32+
33+
This guide is intended for the users of the LLVM with Clang/GCC for
34+
Eclipse CDT plugin. It describes the initial configuration, general
35+
information and some special cases about the plugin.
36+
37+
* xref:general.adoc[General information]
38+
* xref:initial_configuration.adoc[Initial configuration]
39+
* xref:llvm_specific.adoc[LLVM specific information and options]

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<toc label="LLVM plug-in for Eclipse CDT">
3+
<topic label="User manual" href="llvm/user_manual.htm">
4+
<topic label="General information about the plugin" href="llvm/general.htm"/>
5+
<topic label="Initial configuration" href="llvm/initial_configuration.htm"/>
6+
<topic label="LLVM specific information and options" href="llvm/llvm_specific.htm">
7+
</topic>
8+
</topic>
9+
</toc>

‎llvm/org.eclipse.cdt.managedbuilder.llvm.ui/build.properties‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,6 @@ bin.includes = plugin.xml,\
88
about.ini,\
99
about.mappings,\
1010
about.properties,\
11-
cdt_logo_icon32.png,\
12-
help/
11+
cdt_logo_icon32.png
1312
src.includes = patches/,\
14-
help/,\
1513
about.html

0 commit comments

Comments
 (0)