diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore
deleted file mode 100644
index 7cb3f4e9213..00000000000
--- a/doc/org.eclipse.cdt.doc.user/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-/html/
-/workspace/
diff --git a/doc/org.eclipse.cdt.doc.user/README.md b/doc/org.eclipse.cdt.doc.user/README.md
index a889d071619..d4872bfb308 100644
--- a/doc/org.eclipse.cdt.doc.user/README.md
+++ b/doc/org.eclipse.cdt.doc.user/README.md
@@ -11,3 +11,43 @@ During content development, HTML files may be generated by invoking Maven locall
```
mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources
```
+## Embedding commands in help
+
+Embedding commands in help needs to modify syntax slightly.
+Links in adoc are always surrounded by double-quotes, therefore single-quotes (`'`) or escaped double-quote (`"`) need to be used in the command, as appropriate, this is opposite to the quoting that is shown in the Eclipse help [documentation](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command_authoring.htm).
+See the [Eclipse help for general information](https://help.eclipse.org/latest/topic/org.eclipse.platform.doc.isv/guide/ua_help_content_command.htm).
+
+e.g. opening a preference page can be done like this:
+
+`
+image:command_link.png[] link:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)')[General > Editors]
+`
+
+Notes:
+
+- The `livehelp.js` is included automatically with `docinfo-header.htm`
+- `PLUGINS_ROOT` cannot be used within the adoc files, so use `image:command_link.png[]` instead
+
+## Converting html CDT help to adoc
+
+Use pandoc, e.g.:
+
+```
+pandoc getting_started/cdt_w_basic.htm -o src/getting_started/cdt_w_basic.adoc
+# or a whole group of files
+for i in getting_started/*; do pandoc -o src/${i%.*}.adoc $i; done
+```
+
+Apply these changes after:
+
+- Replace `image:../images/` -> `image:` because we use images in different locations depending on whether we are in GitHub or in online help
+- Replace `link:([^[]+).htm\[` -> `xref:$1.adoc[` so that links are always to `adoc` files. Asciidoctor will change that to `htm` on generation so if target has not been converted yet that is ok. This allows links to work when asciidoctor generates for other formats
+- Fix anchors `\[#([^\]]+)\]####` -> `[[$1]]`
+- Fix unneeded ` ` with `\u00A0` -> nothing (some of these were used to indent makefiles, but that meant they couldn't be copied and pasted anyway, so another solution is needed)
+- Remove doubled-up line continuation characters `^\+\n \+` -> `+`
+- Remove extra `+` around horizontal rulers (lines with `'''''`) `'''[\n\s]+\+` -> `'''` and ` *\+[\n\s]+'''` -> `'''`
+- Removed unneeded line breaks `(.) \+$` -> `$1` (lines that have just `+` are [list continuation](https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation))
+- Since `C++` uses a double `+` it can confuse asciidoc, replace `C\+\+` -> `{cpp}` (the C++ attribute). See [Character Replacement Attributes Reference](https://docs.asciidoctor.org/asciidoc/latest/attributes/character-replacement-ref/) for all built-in attributes.
+- Remove copyright statements from bottom of files (the `docinfo-footer.htm` has copyright)
+- Fix the related concepts/tasks in the footer (convert to lists?)
+- Add the headers to the adoc file to enable all the features and ensure consistent copyrights. See adoc-headers.txt
diff --git a/doc/org.eclipse.cdt.doc.user/adoc-headers.txt b/doc/org.eclipse.cdt.doc.user/adoc-headers.txt
new file mode 100644
index 00000000000..f95f747c542
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/adoc-headers.txt
@@ -0,0 +1,29 @@
+////
+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
diff --git a/doc/org.eclipse.cdt.doc.user/asciidoc/coderay-asciidoctor.css b/doc/org.eclipse.cdt.doc.user/asciidoc/coderay-asciidoctor.css
new file mode 100644
index 00000000000..83b9d7e5482
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/asciidoc/coderay-asciidoctor.css
@@ -0,0 +1,87 @@
+/*! Stylesheet for CodeRay to loosely match GitHub themes | MIT License */
+pre.CodeRay{background:#f7f7f8}
+.CodeRay .line-numbers{border-right:1px solid;opacity:.35;padding:0 .5em 0 0;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}
+.CodeRay span.line-numbers{display:inline-block;margin-right:.75em}
+.CodeRay .line-numbers strong{color:#000}
+table.CodeRay{border-collapse:separate;border:0;margin-bottom:0;background:none}
+table.CodeRay td{vertical-align:top;line-height:inherit}
+table.CodeRay td.line-numbers{text-align:right}
+table.CodeRay td.code{padding:0 0 0 .75em}
+.CodeRay .debug{color:#fff!important;background:navy!important}
+.CodeRay .annotation{color:#007}
+.CodeRay .attribute-name{color:navy}
+.CodeRay .attribute-value{color:#700}
+.CodeRay .binary{color:#509}
+.CodeRay .comment{color:#998;font-style:italic}
+.CodeRay .char{color:#04d}
+.CodeRay .char .content{color:#04d}
+.CodeRay .char .delimiter{color:#039}
+.CodeRay .class{color:#458;font-weight:bold}
+.CodeRay .complex{color:#a08}
+.CodeRay .constant,.CodeRay .predefined-constant{color:teal}
+.CodeRay .color{color:#099}
+.CodeRay .class-variable{color:#369}
+.CodeRay .decorator{color:#b0b}
+.CodeRay .definition{color:#099}
+.CodeRay .delimiter{color:#000}
+.CodeRay .doc{color:#970}
+.CodeRay .doctype{color:#34b}
+.CodeRay .doc-string{color:#d42}
+.CodeRay .escape{color:#666}
+.CodeRay .entity{color:#800}
+.CodeRay .error{color:#808}
+.CodeRay .exception{color:inherit}
+.CodeRay .filename{color:#099}
+.CodeRay .function{color:#900;font-weight:bold}
+.CodeRay .global-variable{color:teal}
+.CodeRay .hex{color:#058}
+.CodeRay .integer,.CodeRay .float{color:#099}
+.CodeRay .include{color:#555}
+.CodeRay .inline{color:#000}
+.CodeRay .inline .inline{background:#ccc}
+.CodeRay .inline .inline .inline{background:#bbb}
+.CodeRay .inline .inline-delimiter{color:#d14}
+.CodeRay .inline-delimiter{color:#d14}
+.CodeRay .important{color:#555;font-weight:bold}
+.CodeRay .interpreted{color:#b2b}
+.CodeRay .instance-variable{color:teal}
+.CodeRay .label{color:#970}
+.CodeRay .local-variable{color:#963}
+.CodeRay .octal{color:#40e}
+.CodeRay .predefined{color:#369}
+.CodeRay .preprocessor{color:#579}
+.CodeRay .pseudo-class{color:#555}
+.CodeRay .directive{font-weight:bold}
+.CodeRay .type{font-weight:bold}
+.CodeRay .predefined-type{color:inherit}
+.CodeRay .reserved,.CodeRay .keyword{color:#000;font-weight:bold}
+.CodeRay .key{color:#808}
+.CodeRay .key .delimiter{color:#606}
+.CodeRay .key .char{color:#80f}
+.CodeRay .value{color:#088}
+.CodeRay .regexp .delimiter{color:#808}
+.CodeRay .regexp .content{color:#808}
+.CodeRay .regexp .modifier{color:#808}
+.CodeRay .regexp .char{color:#d14}
+.CodeRay .regexp .function{color:#404;font-weight:bold}
+.CodeRay .string{color:#d20}
+.CodeRay .string .string .string{background:#ffd0d0}
+.CodeRay .string .content{color:#d14}
+.CodeRay .string .char{color:#d14}
+.CodeRay .string .delimiter{color:#d14}
+.CodeRay .shell{color:#d14}
+.CodeRay .shell .delimiter{color:#d14}
+.CodeRay .symbol{color:#990073}
+.CodeRay .symbol .content{color:#a60}
+.CodeRay .symbol .delimiter{color:#630}
+.CodeRay .tag{color:teal}
+.CodeRay .tag-special{color:#d70}
+.CodeRay .variable{color:#036}
+.CodeRay .insert{background:#afa}
+.CodeRay .delete{background:#faa}
+.CodeRay .change{color:#aaf;background:#007}
+.CodeRay .head{color:#f8f;background:#505}
+.CodeRay .insert .insert{color:#080}
+.CodeRay .delete .delete{color:#800}
+.CodeRay .change .change{color:#66f}
+.CodeRay .head .head{color:#f4f}
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/asciidoc/example.htm b/doc/org.eclipse.cdt.doc.user/asciidoc/example.htm
new file mode 100644
index 00000000000..6cade717154
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/asciidoc/example.htm
@@ -0,0 +1,141 @@
+
+
+
+
+
+
+
+Example document
+
+
+
+
+
+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
-
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm
index e157f3f2474..f8bad0785be 100644
--- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm
+++ b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm
@@ -1,166 +1,242 @@
-
+
-
- New CDT Project with generated makefile - Tutorial
-
-
+
+
+
+
+Tutorial: Creating a simple application
+
+
-
-
Tutorial: Creating a simple application
-
-
In this tutorial, you will use the CDT to create a simple 'Hello World' application.
-This tutorial describes the process of creating a new C++ project where the build is
-automatically managed by the CDT, and running the program.
-
-
NOTE: In earlier versions of the CDT, there were two separate project types:
-Managed make (automatically generated a makefile)
-and Standard make (required the user's makefile to build).
-Now with CDT, you just select a project type, and that determines what build system to use.
-
-
To create a simple "Hello World" application using CDT, perform the following general steps:
In this tutorial, you will use the CDT to create a simple 'Hello World'
+application. This tutorial describes the process of creating a new C++
+project where the build is automatically managed by the CDT, and running
+the program.
+
+
+
NOTE: In earlier versions of the CDT, there were two separate project
+types: Managed make (automatically generated a makefile) and Standard
+make (required the user’s makefile to build). Now with CDT, you just
+select a project type, and that determines what build system to use.
+
+
+
To create a simple "Hello World" application using CDT, perform the
+following general steps:
Select the type of project to create. For this tutorial, expand the C++ folder and select C++ Project and click Next.
-
-
-
-
-
-
The C++ Project wizard opens.
-
-
- By default, the CDT filters the Toolchain and Project types that it displays in those lists based on the language support for the C++ Project wizard you selected for this tutorial.
-
-
-
-
-
In the Project name field, type a name for the project, such as HelloWorld.
-
-
-
-
From the Project type list, expand Executable and select Hello World C++ Project. This project type provides a simple Hello World application in C++, and the makefile is automatically created by the CDT.
-
-
-
-
Select a required toolchain from the Toolchain list.
-
-
-
A toolchain is a set of tools (such as a compiler, linker, and assembler) intended to build your project.
- Additional tools, such as a debugger, can be associated with a toolchain.
- There can be several toolchains available, depending on the compilers installed on your system.
-
-
-
-
Click Next.
-
-
-
-
-
-
-
Specify the Basic Properties for the new project, such as your author, copyright, and source information, then click Next.
-
-
-
-
-
-
The Select Configurations page displays a list of configurations based on the project type and toolchain(s) selected earlier.
-
-
-
- OPTIONAL: If you want to change the default project settings, click Advanced Setting to open the Project Properties dialog for your new project allowing you change any of the project specific settings,
- such as includes paths, compiler options, and libraries.
-
-
-
Click Finish.
-
-
-
NOTE If the C++ perspective is not currently set as the default, you are prompted to determine if you would like to this project to be associated with the C/C++ perspective. Click Yes.
-
-
A project is created with the default settings and a full set of configurations based on the project type and toolchain you selected.
- You should now see the new project in Project Explorer view.
-
-
+
+
Step 1: Creating a project
+
+
+
+
Select File > New > Project.
-
+
+
+
+
Select the type of project to create. For this tutorial, expand the
+C++ folder and select C++ Project and click Next.
+
+
+
+
+
+
The C++ Project wizard opens.
+
+
+
+By default, the CDT filters the Toolchain and Project types that it
+displays in those lists based on the language support for the C++
+Project wizard you selected for this tutorial.
+
+
+
+
+
In the Project name field, type a name for the project, such as
+HelloWorld.
+
+
+
From the Project type list, expand Executable and select Hello
+World C++ Project. This project type provides a simple Hello World
+application in C++, and the makefile is automatically created by the
+CDT.
+
+
+
Select a required toolchain from the Toolchain list.
+
+
A toolchain is a set of tools (such as a compiler, linker, and
+assembler) intended to build your project. Additional tools, such as a
+debugger, can be associated with a toolchain. There can be several
+toolchains available, depending on the compilers installed on your
+system.
+
+
+
+
Click Next.
+
+
+
+
+
+
Specify the Basic Properties for the new project, such as your
+author, copyright, and source information, then click Next.
-
Step 2: Reviewing the code and building the project
-
-
From the Project Explorer view, double-click the .cpp file created for your project, for example, HelloWorld.cpp. You'll find it within the project "src" folder.
-
-
This file opens in a default editor. It contains C++ template code for the Hello World example project you selected earlier. In addition, the Outline view has also been populated
- with objects created from your code.
-
-
-
- NOTE: You can specify a different editor, and add or modify existing code templates in Window > Preferences.
-
- OPTIONAL: You can type additional code in this file, and then save the changes by clicking File > Save, or pressing CTRL+S.
-
- Next, you will need to build your project before you can run it.
-
-
-
-
Build your project by pressing CTRL+B, or select the project in the Project Explorer view and select Project > Build Project.
-
-
Read through the build messages in the Console view.
-The project should build successfully.
+
+
+
+
+
The Select Configurations page displays a list of configurations
+based on the project type and toolchain(s) selected earlier.
+
-
You will also see the Outline view has also been populated
-with objects created from your code. If you select an item from the Outline view, the
-corresponding text in the editor is highlighted.
-
-
+OPTIONAL: If you want to change the default project settings, click
+Advanced Setting to open the
+Project Properties dialog for your
+new project allowing you change any of the project specific settings,
+such as includes paths, compiler options, and libraries.
+
+
+
+
Click Finish.
+
+
+
+
+
NOTE If the C++ perspective is not currently set as the default, you
+are prompted to determine if you would like to this project to be
+associated with the C/C++ perspective. Click Yes.
+
+
+
A project is created with the default settings and a full set of
+configurations based on the project type and toolchain you selected. You
+should now see the new project in
+Project Explorer
+view.
+
+
+
+
+
+
+
Step 2: Reviewing the code and building the project
+
+
+
+
From the Project Explorer view, double-click the .cpp file created
+for your project, for example, HelloWorld.cpp. You’ll
+find it within the project "src" folder.
+
+
This file opens in a default editor. It contains C++ template code for
+the Hello World example project you selected earlier. In addition, the
+Outline view has also been
+populated with objects created from your code.
+
+
-
Step 3: Running the application
-
+NOTE: You can specify a different editor, and add or modify existing
+code templates in Window > Preferences.
+
+OPTIONAL: You can type additional code in this file, and then save the
+changes by clicking File > Save, or pressing CTRL+S.
+
+Next, you will need to build your project before you can run it.
+
+
+
+
+
Build your project by pressing CTRL+B, or select the project in the
+Project Explorer view and select Project > Build Project.
Read through the build messages in the
+Console view. The project
+should build successfully.
+
+
You will also see the Outline view has also been populated with
+objects created from your code. If you select an item from the Outline
+view, the corresponding text in the editor is highlighted.
+
+
+
+
+
+
+
+
Step 3: Running the application
+
To run your application:
-
-
Within the C/C++ Perspective, click Run > Run Configurations....
-
Select C/C++ Application.
-
Click New.
-
-
-
A new Run Configuration is created. Its name and path to the executable are provided by the project ('Hello World' in our case).
-
-
Click Run.
-
-
Now, you should see the Hello World application running in the Console view.
-The Console also shows which application is running in a title bar.
-
-
You can click the other views to see the information that they contain.
-
-
-
+
+
+
+
+
Within the C/C++ Perspective, click Run > Run Configurations….
+
+
+
Select C/C++ Application.
+
+
+
Click New.
+
+
A new Run Configuration is created. Its name and path to the executable
+are provided by the project ('Hello World' in our case).
+
+
+
+
Click Run.
+
+
Now, you should see the Hello World application running in the Console
+view. The Console also shows which application is running in a title
+bar.
+
+
+
+
You can click the other views to see the information that they
+contain.
+
+
+
+
+
+
+
+
-
-
+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
+
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm
index dde9e59c20c..a7ea8b29797 100644
--- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm
+++ b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm
@@ -1,65 +1,116 @@
-
+
-
-
- Building your project
-
-
+
+
+
+
+Building a project
+
+
-
-
Building a project
-
+
+
+
+
+
+
+
Building a project
+
+
The make output and build progress information displays in the
- Console view. The Make Targets view displays makefile actions, and the
-Problems view displays compile warnings or errors.
-
To build a project:
-
-
In the Project Explorer view, select your project. For the tutorial, you can select the HelloWorld project you created earlier.
-
Click Project > Build Project, or click the build icon on the toolbar.
-
If you see an error message, such as:
-
(Cannot run program "make": Launching failed)
-
then CDT cannot locate the build command, usually make.
-Either your path is not configured correctly, or you do not have make
-installed on your system.
-
You can see in the Console view the output and results of the build command.
-Click on its tab to bring the view forward if it is not currently visible.
-If for some reason it's not present, you can open it by selecting Window > Show View > Console.
-
+Console view. The
+Make Targets view
+displays makefile actions, and the
+Problems view displays
+compile warnings or errors.
+
+
+
To build a project:
+
+
+
+
In the Project Explorer view, select your project. For the tutorial,
+you can select the HelloWorld project you created earlier.
+
+
+
Click Project > Build Project, or click the build icon
+ on the toolbar.
+
+
+
If you see an error message, such as:
+
+
+
(Cannot run program "make": Launching failed)
+
+
+
then CDT cannot locate the build command, usually make. Either your
+path is not configured correctly, or you do not have make installed on
+your system.
+
+
+
+
+
You can see in the Console view the output and results of the build
+command. Click on its tab to bring the view forward if it is not
+currently visible. If for some reason it’s not present, you can open it
+by selecting Window > Show View > Console.
-
+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
+
+
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm
index 4697ba53684..1bbd950069c 100644
--- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm
+++ b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm
@@ -1,132 +1,209 @@
-
+
-
-
-
- Debugging your project
-
+
+
+
+
+Debugging a project
+
+
-
-
-
-
Debugging a project
-
-
The debugger lets you control the execution of your program by setting
-breakpoints, suspending executed programs, stepping through your code, and
-examining the contents of variables.
-
To debug a project:
-
-
Click the Run > Debug Configurations... menu option.
-
-
The DebugConfigurations dialog opens.
-
-
-
-
-
Double-click C/C++ Application to create a new launch configuration.
-
-
-
-
If a project is selected in the Project Explorer view the following data is automatically entered, take a moment to verify its accuracy or change as needed.
-
-
-
-
In the Name edit box, type the project name, like Hello World.
-
- You can now select this debug launch configuration by name the next time
- that you debug this project.
-
-
-
In the C/C++ Application edit box, type the name of the executable if its not already entered.
-
- If not, click the Search Project button to locate the executable in the project.
-
-
-
-
In the Project edit box, type or choose your project, e.g. HelloWorld.
-
-
-
NOTE If you see the error "[Debugger]: No debugger available", select the Debugger tab
- and choose a valid debugger for your platform (e.g. gdb/mi).
-
-
-
-
-
-
Click Debug.
-
You may be prompted to switch to the Debug perspective. Click Yes
-
The Debug perspective appears with the helloworld.exe application window open.
- The C/C++ editor repositions in the perspective.
-
+
+
+
+
+
+
+
Debugging a project
+
+
+
The debugger lets you control the execution of your program by setting
+breakpoints, suspending executed programs, stepping through your code,
+and examining the contents of variables.
+
+
+
To debug a project:
+
+
+
+
Click the Run > Debug Configurations… menu option.
+
+
The DebugConfigurations dialog opens.
-
NOTE: If you see the error "Can't find source file" in the editor view, use the Locate File button
- to locate your source file.
-
-
-
-
-
In the left margin of the main.cpp window, double-click to set a
- breakpoint on:
-
- cout << You just entered
-
-
- You'll see a blue circle () there indicating the breakpoint is set.
-
-
-
-
Click Run > Resume.
-
-
- Or, you can use the Resume button () on the toolbar of the Debug view
- .
-
-
-
When prompted, in the Console view, type a value other than 'm', and press Enter.
-
- The breakpoint will be hit.
-
-
-
In the Variables view, verify that the variable is not 'm'.
-
-
-
Click Run > Resume.
-
-
-
When prompted, again type a value other than 'm' in the Console view, and press Enter.
-
The breakpoint will be hit.
-
In the Variables view, verify that the variable is not 'm'.
-
-
-
In the Variables view, right-click the input variable, and select Change Value...
- and type 'm'between the single quotes and hit OK.
-
-
-
Click Run > Resume.
-
The output in the helloworld.exe application window is: "Thank you. Exiting."
-
-
The application terminates and the debug session ends. The Debug perspective remains open.
+
+
+
+
+
+
Double-click C/C++ Application to create a new launch
+configuration.
+
+
+
+
+
If a project is selected in the
+Project Explorer view
+the following data is automatically entered, take a moment to verify its
+accuracy or change as needed.
+
+
+
+
+
+
In the Name edit box, type the project name, like Hello World.
+
+You can now select this debug launch configuration by name the next time
+that you debug this project.
+
+
+
+
In the C/C++ Application edit box, type the name of the executable
+if its not already entered.
+
+If not, click the Search Project button to locate the executable in
+the project.
+
+
+
+
In the Project edit box, type or choose your project, e.g.
+HelloWorld.
+
+
NOTE If you see the error "[Debugger]: No debugger
+available", select the Debugger tab and choose a valid debugger for
+your platform (e.g. gdb/mi).
+
+
+
-
To learn more about debugging, see the related debug conceptual topics.
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
+
\ No newline at end of file
diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm
index ca040c2624a..083384b0483 100644
--- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm
+++ b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm
@@ -1,211 +1,289 @@
-
+
-
-
- How to bring C/C++ source files into Eclipse
-
+
+
+
+
+Importing your C/C++ source files into Eclipse
+
+
-
-
-
-
Importing your C/C++ source files into Eclipse
-
-
Using the CVS Repository Exploring perspective, you can check
-out modules or directories into existing projects, or create new
-projects. A common scenario that you may encounter when starting to use the CDT, is determining how
-to bring existing C/C++ source files into Eclipse. There are a number of ways to
-do this. The scenarios described below are recommended approaches.
-
-
Creating a project from source files in CVS
-
-
If your existing source tree is managed in CVS, you can use the CVS
-Repository perspective to "Checkout As..." any folder in the repository.
-The first time you "Checkout As...", the New Project wizard launches and you need to
-create a C or C++ project for the folder. For more information, see
-Creating a project,
-Creating a project via a project template and
-Working with C/C++ project files.
-
-
After you perform a checkout operation, a CVS checkout of the project occurs into the project's location. It is recommended that you eventually add and commit the CDT project files back into CVS.
-These files include .project, .cdtproject, and .cdtbuild (for Managed Build projects) and are located at the root folder of each CDT project.
-
-
-Bringing code into the IDE from CVS differs slightly, depending on what
-you're importing:
-
-
+
+
+
+
+
+
+
Importing your C/C++ source files into Eclipse
+
+
+
Using the CVS Repository Exploring perspective, you can check out
+modules or directories into existing projects, or create new projects. A
+common scenario that you may encounter when starting to use the CDT, is
+determining how to bring existing C/C++ source files into Eclipse. There
+are a number of ways to do this. The scenarios described below are
+recommended approaches.
+
+
+
Creating a project from source files in CVS
+
+
If your existing source tree is managed in CVS, you can use the CVS
+Repository perspective to "Checkout As…" any folder in the repository.
+The first time you "Checkout As…", the New Project wizard launches and
+you need to create a C or C++ project for the folder. For more
+information, see Creating a project,
+Creating a project via a
+project template and Working with
+C/C++ project files.
+
+
+
After you perform a checkout operation, a CVS checkout of the project
+occurs into the project’s location. It is recommended that you
+eventually add and commit the CDT project files back into CVS. These
+files include .project, .cdtproject, and .cdtbuild (for Managed Build
+projects) and are located at the root folder of each CDT project.
+
+
+
Bringing code into the IDE from CVS differs slightly, depending on what
+you’re importing:
+
+
-
an existing C/C++ project
-
-
-
existing C/C++ code that isn't part of a project
-
-
-
- existing C/C++ code that needs to be added to an existing project
-
+
+
an existing C/C++ project
+
+
+
existing C/C++ code that isn’t part of a project
+
+
+
existing C/C++ code that needs to be added to an existing project
+
-
-
Importing a C/C++ project from CVS
-
-
-To check out an existing C/C++ project from the CVS repository into your workspace, right-click the project in the CVS Repositories view, and select Check Out from the menu. A project with the same name as the CVS module is checked out in to your workspace.
-
-
-
-
Importing C/C++ code from CVS
-
-
-To check out existing C/C++ code that is not part of a project:
-
-
-
-
- Right-click the module or directory in the CVS
- Repositories view and choose Check Out As...
- from the menu.
-
-
- The Check Out As wizard displays.
-
-
-
-
-
- Choose how to check out this project:
-
-
-
- as a project configured using the New Project
- wizard
-
-
- or:
-
-
-
-
- as a new project in the workspace
-
-
- or:
-
-
-
-
- as a Standard Make C/C++ Project - if you need to create your own
- Makefile to integrate with an existing build
- process
-
-
-
-
- Choose the workspace location for this project, then the CVS
- tag to check out.
-
Click Finish to exit the Check Out As dialog.
-
-
-
Click Next to continue.
+
+
+
Importing a C/C++ project from CVS
+
+
To check out an existing C/C++ project from the CVS repository into your
+workspace, right-click the project in the CVS Repositories view, and
+select Check Out from the menu. A project with the same name as the
+CVS module is checked out in to your workspace.
+
+
+
+
Importing C/C++ code from CVS
+
+
To check out existing C/C++ code that is not part of a project:
+
+
+
+
+
Right-click the module or directory in the CVS Repositories view and
+choose Check Out As… from the menu.
+
+
The Check Out As wizard displays.
+
+
+
+
Choose how to check out this project:
+
+
+
+
as a project configured using the New Project wizard
+
+
or:
+
+
+
+
as a new project in the workspace
+
+
or:
+
+
+
+
as a Standard Make C/C++ Project - if you need to create your own
+Makefile to integrate with an existing build process
+
+
Choose the workspace location for this project, then the CVS tag to
+check out.
+
+
+
+
+
+
+
Click Finish to exit the Check Out As dialog.
+
+
+
Click Next to continue.
+
-
-
Importing C/C++ code into an existing project
-
-
-To import a directory full of C/C++ code into an existing project:
-
-
-
-
- Right-click the module or directory in the CVS
- Repositories view and choose Check Out As
- from the menu.
-
-
- The IDE displays the Check Out As dialog.
-
-
-
Choose Check out into an existing project, and then click
- Next.
- The IDE displays the Check Out Into dialog:
-
-
-
-
- Select an existing project from the list, and then
- click Finish to add the code from CVS to the selected
- project.
-
+
+
+
+
Importing C/C++ code into an existing project
+
+
To import a directory full of C/C++ code into an existing project:
+
+
+
+
+
Right-click the module or directory in the CVS Repositories view and
+choose Check Out As from the menu.
+
+
The IDE displays the Check Out As dialog.
+
+
+
+
Choose Check out into an existing project, and then click Next.
+The IDE displays the Check Out Into dialog:
+
+
+
Select an existing project from the list, and then click Finish to
+add the code from CVS to the selected project.
+
-
-
-
Creating new projects from existing source roots
-
-If your resource code is not managed in CVS but is available from the file system, then you need to perform two steps:
-
-
Identify a "root folder" of your source code tree.
-
Create a new C/C++ project using the New Project Wizard, and specify the "root folder" as a non-default location of the new project.
+
+
+
+
+
Creating new projects from existing source roots
+
+
If your resource code is not managed in CVS but is available from the
+file system, then you need to perform two steps:
+
+
+
+
+
Identify a "root folder" of your source code tree.
+
+
+
Create a new C/C++ project using the New Project Wizard, and specify
+the "root folder" as a non-default location of the new project.
+
-
Typically, existing projects will have their own makefiles, so you should create a new Make C/C++ project. For more information see
+
To help you to identify a root folder for your project, consider the
+following guidelines:
+
+
+
+
+
all source code for the project is available on or beneath the root
+folder
+
+
+
the build results are also produced in or beneath the root folder
+
+
+
there is often a makefile in the root folder. In complex projects, the
+makefile in the root folder calls other makefiles in other directories
+to produce the build results.
+
+
+
external header files and library files do not need to be in or
+beneath the root folder.
+
+
+
+
+
The resources for the project are maintained in the remote location
+specified, not in the workspace folder for Eclipse. However, your
+existing folder structure is displayed in the C/C++ Projects view. Meta
+data for the project, such as the index for the project and the link to
+the existing source, is stored in the metadata directory in the
+workspace folder. For more information on the workspace folder, see
+Workbench User Guide > Tasks > Upgrading Eclipse.
+
+
+
After you create a CDT project, you cannot easily move it or redefine
+its root folders. If you need to, you can delete the CDT project
+(without deleting its contents) and then recreate it specifying a
+different non-default location.
+
+
+
+
Import your C/C++ source file system
+
+
Another approach would be to create a C/C++ Project and then import your
+existing file system. For more information about importing, see
+Workbench User Guide > Tasks > Importing > Importing resources from the
+file system.
+
+
+
This approach copies the files from your file system to an Eclipse
+Workbench project or folder. Your original source files remain unchanged
+and it is the copies of the files that will be edited, built and
+debugged using the CDT. When you have successfully imported your
+existing file system, the folder structure is displayed in the C/C++
+Projects view. Again, you should identify an appropriate "root folder"
+to import from.
+
+
+
Tip:
+
+
+
+
Importing your existing file system can consume significant disk space
+depending on the size of your files.
+
+
+
Your files may become detached from an existing source control system
+that previously referenced the original file location such as a
+ClearCase view.
+
+
+
+
+
+
+
-
all source code for the project is available on or beneath the root folder
-
the build results are also produced in or beneath the root folder
-
there is often a makefile in the root folder. In complex projects, the makefile in the root folder calls other makefiles in other directories to produce the build results.
-
external header files and library files do not need to be in or beneath the root folder.
-
-
-
The resources for the project are maintained in the remote location specified,
-not in the workspace folder for Eclipse. However, your existing folder structure
-is displayed in the C/C++ Projects view. Meta data for the project, such as the
-index for the project and the link to the existing source, is stored in the metadata
-directory in the workspace folder. For more information on the workspace folder,
-see Workbench User Guide > Tasks > Upgrading Eclipse.
-
-After you create a CDT project, you cannot easily move it or redefine its root folders.
-If you need to, you can delete the CDT project (without deleting its contents) and then
-recreate it specifying a different non-default location.
-
-
Import your C/C++ source file system
-
-
Another approach would be to create a C/C++ Project and then import your
-existing file system.
-
-For more information about importing, see Workbench User Guide > Tasks > Importing >
-Importing resources from the file system.
-
-
This approach copies the files from your file system to an Eclipse Workbench
-project or folder. Your original source files remain unchanged and it is the
-copies of the files that will be edited, built and debugged using the CDT.
-When you have successfully imported your existing file system, the folder
-structure is displayed in the C/C++ Projects view. Again, you should identify an
-appropriate "root folder" to import from.
Importing your existing file system can consume significant disk space
- depending on the size of your files.
-
Your files may become detached from an existing source control system that
- previously referenced the original file location such as a ClearCase view.
In the Project name field, type a name for the project.
-
Ensure that the Use default location option is not selected because here we will specify where the
- resources reside in the file system, in a location other than your workspace.
- We assume this directory location already exists, and contains e.g. source files and makefile. If it does not exist, it
- will be created.
-
In this example, we will use an existing hello.cpp and its
- existing hello.mak makefile, located in the directory c:\brandon.
-
In the Location field, specify the path to the existing files for your project.
-
From the Project types list, expand Makefile Project and select Empty Project..
-
-
To have sample source and a makefile created in your existing directory, select Hello World C++ Project
-
-
Make sure a toolchain is selected.
-
-
Click Next.
-
-
-
(Optional) On the Select Configurations page, select only the configurations you want created. Configurations
- display for each toolchain selected on the previous page of the wizard.
-
Click Finish to close the dialog box.
-
You will see the new project in the Project Explorer view. In addition, new 'dot' files have been created in
- your legacy project's root directory, these are CDT project files.
-
-
(Optional) To see these "hidden" files, open the view menu on the Project explorer view, and select
- "Customize View."
- The view menu is activated via the small downward-pointing triangle in the upper right of the toolbar of the view.
-
To build your project, select Project > Build Project.
- You can also hit the hammer icon on the toolbar to
- build the selected project.
-
-
You may see an error e.g. "make: *** no rule to make target 'all'.
-
This is because, in our case, we didn't tell it where the makefile is, or its name.
-
-
Open the project properties (right mouse on project name in the Project Explorer view
- and select Properties at the bottom on the context menu).
-
On the C/C++ Build Page, on its Builder Settings tab, uncheck Use default build command
- and change the make command to make -f hello.mak
- since our makefile is not named the default makefile.
-
Click OK to close the Project Properties window.
-
-
Your project will probably rebuild. If not you can force a build via
- Project > Build Project
- or use the hammer icon .
-
-
-
After the project build completes, the results display in the Console view and new objects, such as binaries and includes, show in the Project Explorer view.
Review the results to ensure that there are no errors.
-
-
-
-Note: By default, the indexer is set to Fast indexer for the project to parse your project in the same way that a compiler does; beginning with each compilation unit and parsing that file and all files that it includes, except that it parses each header file included in a project only once. This method provides the most accurate index information. For large projects using complex C++ code, this indexer can be slow. For example, if a header file is included and takes two compilation units, the parsing of the second unit reuses the results of parsing the first unit. This is similar to how precompiled headers work. The indexing of large projects using the Fast indexer uses fewer resources than the Full indexer, but the resulting index is not quite as accurate.
- To change indexer settings, bring up the Indexer page in the Project Properties.
-
The following tutorial takes you though the process of importing a
+'legacy' application using the CDT.
+
+
+
Step 1: You want to create a single project that will reflect all of the
+components for the existing source tree.
+
+
+
+
+
Select File > New > Project.
+
+
+
For this tutorial, expand C/C++ and select C++ project.
+
+
The New Project wizard displays.
+
+
+
+
+
In the Project name field, type a name for the project.
+
+
+
Ensure that the Use default location option is not selected because
+here we will specify where the resources reside in the file system, in a
+location other than your workspace.
+We assume this directory location already exists, and contains e.g.
+source files and makefile. If it does not exist, it will be created.
+
+
In this example, we will use an existing hello.cpp and its existing
+hello.mak makefile, located in the directory c:\brandon.
+
+
+
+
+
In the Location field, specify the path to the existing files for
+your project.
+
+
+
From the Project types list, expand Makefile Project and select
+Empty Project..
+
+
+
+
To have sample source and a makefile created in your existing
+directory, select Hello World C++ Project
+
+
+
+
+
+
Make sure a toolchain is selected.
+
+
+
Click Next.
+
+
+
(Optional) On the Select Configurations page, select only the
+configurations you want created. Configurations display for each
+toolchain selected on the previous page of the wizard.
+
+
+
Click Finish to close the dialog box.
+
+
You will see the new project in the Project Explorer view. In addition,
+new 'dot' files have been created in your legacy project’s root
+directory, these are CDT project files.
+
+
+
+
+
(Optional) To see these "hidden" files, open the view menu on the
+Project explorer view, and select "Customize View."
+The view menu is activated via the small downward-pointing triangle in
+the upper right of the toolbar of the view.
+
+
+
+
In the Available Customizations window, on the Filters tab,
+uncheck ".* resources."
+
+
+
+
The formerly hidden 'dot' files are now shown in the Project
+Explorer.
+
+
+
+
Hit OK to close the dialog.
+
+
+
-
+
+
+
Step 2: You are now ready to build your project.
+
+
+
+
+
To build your project, select Project > Build Project.
+You can also hit the hammer icon on the toolbar to build the selected project.
+
+
+
You may see an error e.g. make: *** no rule to make target 'all'.
+
+
This is because, in our case, we didn’t tell it where the makefile is,
+or its name.
+
+
+
+
+
Open the project properties (right mouse on project name in the
+Project Explorer view and select Properties at the bottom on the
+context menu).
+
+
+
On the C/C++ Build Page, on its Builder Settings tab, uncheck ''Use
+default build command'' and change the make command to
+make -f hello.mak since our makefile is not named the default
+makefile.
+
+
+
+
Click OK to close the Project Properties window.
+
+
+
Your project will probably rebuild. If not you can force a build via
+Project > Build Project or use the hammer icon
+.
+
+
After the project build completes, the results display in the Console
+view and new objects, such as binaries and includes, show in the
+Project Explorer view.
+
+
+
+
+
+
+
+
Review the results to ensure that there are no errors.
+
+
Note: By default, the indexer is set to Fast indexer for the project
+to parse your project in the same way that a compiler does; beginning
+with each compilation unit and parsing that file and all files that it
+includes, except that it parses each header file included in a project
+only once. This method provides the most accurate index information. For
+large projects using complex C++ code, this indexer can be slow. For
+example, if a header file is included and takes two compilation units,
+the parsing of the second unit reuses the results of parsing the first
+unit. This is similar to how precompiled headers work. The indexing of
+large projects using the Fast indexer uses fewer resources than the Full
+indexer, but the resulting index is not quite as accurate.
+To change indexer settings, bring up the Indexer page in the Project
+Properties.
+
+
+
Step 3: You are now ready to run your application.
-
-
To run your application within the C/C++ Perspective, click Run > Run Configurations...
-
The Run Configurations dialog displays.
-
To create a run configuration, select C/C++ Application and click the New icon.
-
Give your run configuration a name by entering a new name in the Name field at the top.
-
On the Main tab, select the project by clicking Browse opposite the Project field.
-
-
From the Project Selection window, select the project and click OK.
-
Select the new C/C++ Application you want to execute by clicking Search.
-
In our case it didn't find the file because it's in a nonstandard location.
-Use the Browse button to select the executable. In our case also it's a nonstandard
-name, hello.e because that's what our makefile hello.mak built.
To run your application within the C/C++ Perspective, click Run > Run
+Configurations…
+
+
The Run Configurations dialog displays.
+
+
+
+
To create a run configuration, select C/C++ Application and click
+the New icon.
+
+
+
Give your run configuration a name by entering a new name in the
+Name field at the top.
+
+
+
On the Main tab, select the project by clicking Browse opposite
+the Project field.
+
+
+
+
From the Project Selection window, select the project and click OK.
+
+
+
+
+
+
Select the new C/C++ Application you want to execute by clicking
+Search.
+
+
In our case it didn’t find the file because it’s in a nonstandard
+location. Use the Browse button to select the executable. In our case
+also it’s a nonstandard name, hello.e because that’s what our makefile
+hello.mak built.
+
+
+
-
If you see the error [Debugger]: No debugger available, select the Debugger tab
- and choose a valid debugger for your platform (e.g. gdb/mi).
-
-
-
-
-
Click Run to save the run configuration and run it.
-
The application runs in the Console view. The Console also shows which application it is currently running in the title bar. You can configure the view to display different elements, such as user input elements using different colors.
+
+
If you see the error [Debugger]: No debugger available, select the
+Debugger tab and choose a valid debugger for your platform (e.g.
+gdb/mi).
+
+
+
+
+
+
Click Run to save the run configuration and run it.
+
+
+
The application runs in the Console view. The Console also shows
+which application it is currently running in the title bar. You can
+configure the view to display different elements, such as user input
+elements using different colors.
+
+
-
-
-
+
+
+
+
+
+
+
Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation
- 
- 
-
on the toolbar.
- 
-
-
) there indicating the breakpoint is set.
- 
) on the toolbar of the Debug view
- .
