From 21f46f7468cd73524de18da54a273ad42fafa08e 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.
---
 .../src/getting_started/cdt_w_newproj.adoc    |  3 +-
 .../getting_started/core_build_system.adoc    | 68 +++++++++++++++++++
 .../topics_Getting_Started.xml                |  1 +
 3 files changed, 70 insertions(+), 2 deletions(-)
 create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/core_build_system.adoc

diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc
index c63151aa4c7..bcae2ca3619 100644
--- a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc
+++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc
@@ -142,8 +142,7 @@ at any time by right-clicking on the project in the *Project Explorer*
 view and clicking Properties.
 
 xref:cdt_w_newcpp.adoc[image:ngnext.gif[Next
-Icon,width=16,height=16]] xref:cdt_w_newcpp.adoc[*Next: Creating your {cpp}
-file*]
+Icon,width=16,height=16]] xref:core_build_system.adoc[*Next: Core Build System*]
 
 For more information about:
 
diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/core_build_system.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/core_build_system.adoc
new file mode 100644
index 00000000000..544ef6ccb29
--- /dev/null
+++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/core_build_system.adoc
@@ -0,0 +1,68 @@
+////
+Copyright (c) 2025 Intel corporation 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 a56bb476be4..44e29f99ef1 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="getting_started/core_build_system.htm"/>
           <topic label="Creating a CMake project" href="getting_started/new_cmake_proj.htm"/>
           <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"/>