From 52df7f8ad322794ec25dacd4516a05dbead44efb Mon Sep 17 00:00:00 2001
From: Erwin Waterlander <erwin.waterlander@intel.com>
Date: Thu, 12 Dec 2024 12:35:52 +0000
Subject: [PATCH] Description of the Core Build System.

A brief explanation of what the Core Build System is for end users.
---
 .../getting_started/cdt_w_newproj.htm         |  6 +-
 .../src/asciidoc/core_build_system.adoc       | 68 +++++++++++++++++++
 .../topics_Getting_Started.xml                |  1 +
 3 files changed, 72 insertions(+), 3 deletions(-)
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/asciidoc/core_build_system.adoc

diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm
index 48dec435d7d..6b010f1f30c 100644
--- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm
+++ b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm
@@ -99,8 +99,8 @@
 <p><strong>Tip:</strong> You can view and modify the properties of your
 HelloWorld project at any time by right-clicking on the project in the <strong>Project Explorer</strong> 
 view and clicking Properties.</p>  <p><a style="text-decoration: none" href="cdt_w_newcpp.htm"><img
-src="../images/ngnext.gif" height="16" width="16" alt="Next Icon"></a> <a href="cdt_w_newcpp.htm"><strong>
-Next: Creating your C++ file</strong></a></p>  <p>For more information
+src="../images/ngnext.gif" height="16" width="16" alt="Next Icon"></a> <a href="../html/core_build_system.html"><strong>
+Next: Core Build System</strong></a></p>  <p>For more information
 about:</p>  <ul>
 <li>Projects, see <strong>Workbench User Guide > Concepts > Workbench  > Resources
 </strong></li>
@@ -117,4 +117,4 @@
 <p><img src="../images/ng00_04a.gif" ALT="QNX Copyright Statement" ></p>
 
 </div></body>
-</html>
\ No newline at end of file
+</html>
diff --git a/doc/org.eclipse.cdt.doc.user/src/asciidoc/core_build_system.adoc b/doc/org.eclipse.cdt.doc.user/src/asciidoc/core_build_system.adoc
new file mode 100644
index 00000000000..0290d463f23
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/asciidoc/core_build_system.adoc
@@ -0,0 +1,68 @@
+////
+Copyright (c) 2000-2024 QNX Software Systems and others
+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
+////
+
+
+// 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:
+
+= Core Build System
+
+The Core Build System is the successor of the legacy Managed Build
+System.
+
+The classical Makefile projects are based on the Managed Build System.
+Managed Build projects can generate a Makefile based on GUI controlled
+build configurations in the project properties. The user can
+manage the separate build configurations for Run and Debug. There is a
+notion of "active" build configuration, which is the one that gets
+built when the build button is pressed.
+
+The Core Build System is the basis for CMake projects and Core Build
+Makefile projects. The CDT LaunchBar plays a central role and is used
+for building and launching the program. The philosophy is "Build for
+launch". It simplifies the flow a lot.
+
+These are the main differences compared with the Managed Build System:
+
+* No build configurations. No build file (Makefile or
+  CMakeLists.txt) generation. The user writes it by hand. A
+  "helloworld" example build file can be created for new projects.
+* Each new project is created with a launch configuration tied to it.
+* Build settings are presented in the launch configuration Build Settings tab.
+* The LaunchBar determines Run or Debug mode for building. There is no
+  concept of an active build configuration as there is in Managed
+  Build projects.
+* Auto discovery. The project's macro definitions and include paths,
+  needed for indexing, are extracted from the build step. For CMake
+  projects, data is obtained from the generated JSON file. For Makefile
+  projects, data is extracted from the build step console output.
+* Simpler wizards. Creation of a CMake project is via a simple one page
+  wizard. Using existing code is simply done by creating a new project
+  on top of the existing code. It is not necessary to import the project
+  (menu:File[Import...]).
+
+Core Build connects CDT projects to industry standard external build
+systems like CMake, Makefile, and Meson. The removal of the CDT
+specific build configurations allow Core Build projects to be
+easily be shared with other IDEs, command-line use, and Continuous
+Integration (CI) flows.
+
+Thanks to the auto discovery, the indexing of the C/C++ code has
+improved, because all compilation flags are known per file. This is especially
+beneficial for projects that use multiple toolchains in one project.
+
+icon:arrow-circle-right[] link:pass:[../html/new_cmake_proj.html][Next: Creating a CMake project]
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 7a375ba7905..e9badfd7718 100644
--- a/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml
+++ b/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml
@@ -4,6 +4,7 @@
           <topic label="Preparing the Workbench" href="getting_started/cdt_w_prepare_workbench.htm"/>
           <topic label="Creating a simple application" href="getting_started/cdt_w_basic.htm"/>
           <topic label="Creating a Makefile project" href="getting_started/cdt_w_newproj.htm"/>
+          <topic label="Core Build System" href="html/core_build_system.html"/>
           <topic label="Creating a CMake project" href="html/new_cmake_proj.html"/>
           <topic label="Importing an existing project" href="getting_started/cdt_w_import.htm"/>
           <topic href="getting_started/cdt_w_newcpp.htm" label="Creating a C++ file"/>