Getting Started documentation update. (#1056)

* Put Core Build and Managed Build items in separate topics.
* Added two images to Creating a CMake project.
* Added new pages about creating a CBS Makefile project, using
  existing code, launch bar, building, running, and debbuggin
  a project.
* Renamed "Creating a simple application" to "Creating a Managed Build
  System Makefile project" and replaced two images.
* Removed "Creating a Makefile project", because it was duplicate
  information.

Fixes #992

Author: ewaterlander

doc/org.eclipse.cdt.doc.user/images/c_cpp_project_wizard_cmake_properties.png

@@ -0,0 +1,116 @@
+////
+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
+
+== Building a project
+
+During Core Build System (CBS) project creation a launch configuration
+with the same name is created along with it. The Build settings are
+managed in the *Build Settings* tab of the launch configuration.
+
+CBS projects rely on the xref:cbs_launchbar.adoc[Launch Bar]. Make
+sure the launch bar is installed and enabled.
+
+=== Building for Run
+
+. Select the launch configurion of the project you want to build.
+. Select launch mode *Run*.
+. Press the *Build* button in the launch bar.
+. Inspect the build output in the Console window.
+. Find the build results in the Project Explorer.
+
+image:cbs_build.png[Build a project for Run]
+
+=== Building for Debug
+
+To build for Debug:
+
+. Select the launch configurion of the project you want to build.
+. Select launch mode *Debug*.
+. Press the *Build* button.
+. Inspect the build output in the Console window.
+. Find the build results in the Project Explorer.
+
+image:cbs_build_debug.png[Build a project for Debug]
+
+=== Changing build settings
+
+The launch configuration presents separate build settings for launch mode
+Run and Debug. You will see the build settings depending on the selected
+launch mode.
+
+To change Run build settings:
+
+. Set the launch mode to *Run*
+. Edit the project's launch configuration. Click on the gear icon.
+
+image:cbs_edit_launch_config_run.png[Edit launch configuration]
+
+The edit launch configuration wizard will open. Select the *Build
+Settings* tab.
+
+The only settings that can be changed are the build chain, and how
+CMake or Make is called. There are no options to set pre-processor
+symbols or include paths. This makes that the project can easily be
+shared with other IDEs, command line, or continuous integration flows.
+
+The following picture shows the build settings of a CMake project.
+
+image:cbs_build_settings_tab_cmake.png[CMake build settings tab]
+
+=== Makefile projects BUILD_MODE
+
+For CBS Makefile projects the launch mode is passed to `make` via
+environment variable `BUILD_MODE`. In the Makefile you can make use of
+this variable to set the wanted `CFLAGS` per launch mode.
+
+[cols="1,1"]
+|===
+|Launch mode | BUILD_MODE
+
+|Run
+|run
+
+|Debug
+|debug
+|===
+
+Here is some example code that makes use of `BUILD_MODE` to set the
+wanted `CFLAGS`:
+
+[source,makefile]
+----
+ifeq ($(BUILD_MODE),debug)
+	CFLAGS += -g -O0
+else ifeq ($(BUILD_MODE),run)
+	CFLAGS += -O2
+endif
+----
+
+icon:arrow-circle-right[] xref:cbs_run_project.adoc[Next: Running a project]

doc/org.eclipse.cdt.doc.user/images/c_cpp_project_wizard_makefile.png

@@ -0,0 +1,81 @@
+////
+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
+
+== Debugging a project
+
+Debugging a CBS project is done via the xref:cbs_launchbar.adoc[Launch Bar]. Make
+sure the launch bar is installed and enabled.
+
+First build the project for Debug.
+See xref:cbs_build_project.adoc[Building a project].
+
+. Select the launch configuration of the project you want to run.
+. Select launch mode *Debug*.
+. Press the *Debug* button in the launch bar.
+. Confirm the switch to the Debug Perspective.
+
+image:cbs_debug_cmake.png[Launch a CMake project for Debug]
+
+The Perspective will change to *Debug*, and you can start debugging.
+
+image:cbs_debugging.png[Debugging a CMake project]
+
+
+=== Changing debug settings
+
+To change debug settings:
+
+. Set the launch mode to *Debug*
+. Edit the project's launch configuration. Click on the gear icon.
+
+image:cbs_edit_launch_config_debug.png[Edit launch configuration]
+
+The edit launch configuration wizard will open. Notice that there are
+now two extra tabs *Debugger* and *Source*, because the launch mode is
+*Debug*. These are not present in launch mode *Run*.
+
+On the *Main* tab you can set an alternative C/C++ application, and
+you can enable or disable build before launch.
+
+On the *Arguments* tab you specify optional arguments, and you can
+change the working directory.
+
+On the *Environment* tab you define optional environment variables.
+
+On the *Debugger* tab you can set an alternative debugger. If the
+debugger name is not an absolute path, CDT will look first for the
+debugger in the selected toolchain in the *Build Settings* tab. When
+it is not found in the toolchain the debugger is searched in the
+*PATH* environment variable defined locations.
+
+On the *Source* tab extra paths outside the project folder can be
+defined to look for source code.
+
+image:cbs_launch_config_tab_debug.png[Launch configuration debug tab]

doc/org.eclipse.cdt.doc.user/images/c_cpp_project_wizard_makefile_properties.png

@@ -0,0 +1,55 @@
+////
+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
+
+== Launch Bar
+
+Core Build System (CBS) projects rely on the *Launch Bar*. Make sure
+the _LaunchBar UI_ feature is installed and enabled. In the global
+preferences the launch bar can be enabled or disabled.
+
+image:launchbar_preferences.png[Launch Bar preferences]
+
+The launch bar exists out of several components:
+
+image:launchbar.png[Launch Bar]
+
+. Build button, to launch a build.
+. Run button, to launch a run. This button will change to a Debug
+button in Debug mode.
+. Stop button, to stop a Run or Debug session.
+. Launch mode selector. To change between Run and Debug mode.
+. Launch configuration selector.
+. Edit launch configuration. To change the launch configuration
+properties.
+. Target selector. Not always visible.
+. Edit target.
+
+icon:arrow-circle-right[] xref:cbs_build_project.adoc[Next: Building a
+project]

doc/org.eclipse.cdt.doc.user/images/cbs_build.png

@@ -0,0 +1,67 @@
+////
+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
+
+== Running a project
+
+Running a CBS project is done via the xref:cbs_launchbar.adoc[Launch Bar]. Make
+sure the launch bar is installed and enabled.
+
+First build the project for Run.
+See xref:cbs_build_project.adoc[Building a project].
+
+. Select the launch configuration of the project you want to run.
+. Select launch mode *Run*.
+. Press the *Run* button in the launch bar.
+. Inspect the program output in the Console window.
+
+image:cbs_run_cmake.png[Launch a CMake project for Run]
+
+=== Changing run settings
+
+To change run settings:
+
+. Set the launch mode to *Run*
+. Edit the project's launch configuration. Click on the gear icon.
+
+image:cbs_edit_launch_config_run.png[Edit launch configuration]
+
+The edit launch configuration wizard will open.
+
+On the *Main* tab you can set an alternative C/C++ application, and
+you can enable or disable build before launch.
+
+On the *Arguments* tab you specify optional arguments, and you can
+change the working directory.
+
+On the *Environment* tab you define optional environment variables.
+
+image:cbs_launch_config_tab_main.png[Launch configuration main tab]
+
+icon:arrow-circle-right[] xref:cbs_debug_project.adoc[Next: Debugging a project]

doc/org.eclipse.cdt.doc.user/images/cbs_build_debug.png

@@ -0,0 +1,67 @@
+////
+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
+
+== Using existing code
+
+This tutorial describes how to create a new Core Build System
+(CBS) project for use with existing code.
+
+Using existing code is done by creating a new **empty** CDT project in
+the top directory containing the existing source files. CDT project
+files will be created in the existing source directory.
+
+=== Using an existing CMake project
+
+To create an empty CMake project in CDT select the template *Empty or Existing CMake
+Project* in the *New C/{cpp} Project* wizard.
+
+image:cbs_empty_cmake_project.png[Empty or Existing CMake Project]
+
+In the *New CMake Project* wizard uncheck *Use default location*
+and set the location of the existing code.
+
+image:cbs_existing_code_cmake.png[Existing code CMake]
+
+More information about creating a CMake project is described in
+xref:new_cmake_proj.adoc[Creating a CMake project]
+
+=== Using an existing Makefile project
+
+Create a CBS Makefile project in CDT as described in
+xref:new_cbs_makefile_proj.adoc[Creating a Core Build System Makefile project]
+with the following changes:
+
+In the *New Makefile Project* wizard uncheck *Use default location*,
+set the location of the existing code, and uncheck *Create Hello
+World Source and Makefile example*.
+
+image:cbs_existing_code_makefile.png[Existing code Makefile]
+
+icon:arrow-circle-right[] xref:cbs_launchbar.adoc[Next: Launch Bar]

doc/org.eclipse.cdt.doc.user/images/cbs_build_settings_tab_cmake.png

@@ -36,7 +36,7 @@ Development Toolkit (CDT) to:
 * xref:cdt_w_prepare_workbench.adoc[Prepare the Workbench]
 * xref:cdt_w_basic.adoc[Create a simple application]
 * xref:new_cmake_proj.adoc[Creating a CMake project]
-* xref:cdt_w_newproj.adoc[Create a Makefile project]
+* xref:cdt_w_basic.adoc[Create a Managed Build System Makefile project]
 * xref:cdt_w_import.adoc[Import an existing project]
 * xref:cdt_w_newcpp.adoc[Create a {cpp} file]
 * xref:cdt_w_newmake.adoc[Create a makefile]