Getting Started documentation update. #1056

ewaterlander · 2025-01-23T16:31:13Z

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, and the launch bar.
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

ewaterlander · 2025-01-23T16:34:10Z

Would you like to review this change? It is not finished yet. I'm going to add topics about Building, Running, and Debugging. You can start adding comments.

I separated CBS and MBS.

github-actions · 2025-01-23T16:56:11Z

Test Results

600 files - 34 600 suites - 34 13m 17s ⏱️ - 22m 50s
10 206 tests - 1 217 10 183 ✅ - 1 097 23 💤 - 120 0 ❌ ±0
10 244 runs - 1 194 10 221 ✅ - 1 076 23 💤 - 118 0 ❌ ±0

Results for commit dfcb2fa. ± Comparison against base commit 0fcf41a.

This pull request removes 1217 tests.

org.eclipse.cdt.debug.gdbjtag.core.tests.jtagdevice.GDBJtagDeviceContributionTest ‑ testGdbJtagDeviceContribution
org.eclipse.cdt.debug.gdbjtag.core.tests.launch.GDBJtagLaunchTest ‑ testGdbJtagLaunch[gdb]
org.eclipse.cdt.debug.gdbjtag.core.tests.launch.GDBJtagLaunchTest ‑ testGdbJtagLaunch[gdbserver]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithQuotes[gdb]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithQuotes[gdbserver]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithSpecialSymbols[gdb]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithSpecialSymbols[gdbserver]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithSymbols[gdb]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithSymbols[gdbserver]
org.eclipse.cdt.tests.dsf.gdb.tests.CommandLineArgsTest ‑ testSettingArgumentsWithTabs[gdb]
…

♻️ This comment has been updated with latest results.

jonahgraham · 2025-01-23T17:04:47Z

I'll have a look soon - in the meantime since I don't have an auto comment, the docs are available from this build in https://github.com/eclipse-cdt/cdt/actions/runs/12933695063?pr=1056 (docs link near the bottom)

jonahgraham

Overall this looks very good, I think how you have split it up is very useful.

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_launchbar.adoc

jld01 · 2025-01-24T14:56:10Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_launchbar.adoc

+
+== Launch Bar
+
+CBS projects rely on the *LaunchBar*. Make sure the launch bar plugin


Suggested change

CBS projects rely on the *LaunchBar*. Make sure the launch bar plugin

Core Build System (CBS) projects rely on the *Launch Bar*. Make sure the _LaunchBar UI_ feature

jld01 · 2025-01-24T15:02:48Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+This tutorial describes how to use existing code for Core Build System
+projects.


Suggested change

This tutorial describes how to use existing code for Core Build System

projects.

This tutorial describes how to create a new Core Build System

project for use with existing code.

jld01 · 2025-01-24T15:07:12Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+=== Using an existing CMake project
+
+To create an empty CMake project select the template *Empty or Existing CMake
+Project* in the *New C/{cpp} Project* wizard.


Need to clarify the distinction between a "CMake project" (IDE independent source code) and a "CMake project" (metadata created by CDT).

jld01 · 2025-01-24T15:08:19Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+
+image:cbs_empty_cmake_project.png[Empty or Existing CMake Project]
+
+Then in the *New CMake Project* wizard deselect *Use default location*


Suggested change

Then in the *New CMake Project* wizard deselect *Use default location*

In the *New CMake Project* wizard deselect *Use default location*

jld01 · 2025-01-24T15:09:24Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+=== Using an existing Makefile project
+
+Create a Makefile project as described in


Similarly, distinguish the two uses of "Makefile project" here.

jld01 · 2025-01-24T15:10:03Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+In the *New Makefile Project* wizard deselect *Use default location*
+and set the location of the existing code, and deselect *Create Hello


Suggested change

In the *New Makefile Project* wizard deselect *Use default location*

and set the location of the existing code, and deselect *Create Hello

In the *New Makefile Project* wizard deselect *Use default location*,

set the location of the existing code, and deselect *Create Hello

jld01 · 2025-01-24T15:21:42Z

doc/org.eclipse.cdt.doc.user/src/getting_started/new_cbs_makefile_proj.adoc

+
+

I think multiple empty lines (here and elsewhere) are being interpreted as the end of the numbered list. So the next numbered list item will be item "1" again. Try a single empty line only.

I had some problems with keeping numbered lists together too, I ended up having to add + at the beginning of the blank lines to show list continuation. See https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#list-continuation

jld01

A few comments on your work-in-progress, @ewaterlander. Great to see the documentation being updated.

ewaterlander · 2025-01-24T16:22:51Z

I added three new topics: Building, Running, and Debugging a project. Now the change is complete. I will process the comments on Monday. Thanks. Have a nice weekend!

ewaterlander · 2025-01-27T16:29:08Z

Hi,
I processed the comments.

ewaterlander · 2025-01-29T09:32:27Z

Hi @jld01 and @jonahgraham ,

Could you have a look again? I think the work is done now.

kind regards,
Erwin

betamaxbandit

Hi @ewaterlander ,
thanks for updating the docs.
I've made a few suggestions.
Cheers John

betamaxbandit · 2025-01-29T10:55:44Z

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

Build Settings tab has recently changed a lot
See #1046 (comment)

betamaxbandit · 2025-01-29T12:23:17Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+== Using existing code
+
+This tutorial describes how to create a new Core Build System
+(CBS) project for use with existing code.


It assumes existing code is located in a directory containing source files. Note, CDT project files are written into this directory.

betamaxbandit · 2025-01-29T12:25:28Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+Using existing code is done by creating a new **empty** project on top of the
+existing code.


[I think this task is quite unintuitive for the new user, so it's worth labouring the point about project files, directories etc]
Using existing code is performed by creating a new empty CDT project in the top directory containing the existing source files. With this method, new project files are created, but no new project directory is created.

betamaxbandit · 2025-01-29T12:28:18Z

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_using_existing_code.adoc

+
+image:cbs_empty_cmake_project.png[Empty or Existing CMake Project]
+
+In the *New CMake Project* wizard deselect *Use default location*


[Consider replacing "deselect" with "uncheck". Feels a little more user friendly. There are a couple more occurrences of this below]

jonahgraham

I think @betamaxbandit's comments are worth addressing now, or in a follow-up. I have a TODO in the CDT 12 N&N to update the screenshot:

cdt/NewAndNoteworthy/CDT-12.0.md

Line 23 in 84d99f2

    
           TODO: Before release add the final screenshot for the build settings here. I am not including it now because the UI keeps changing.

But there is some flexibility on that file being updated because it can happen after our last build. The screenshots in the online help need to be updated before final build to populate https://help.eclipse.org/latest/index.jsp and built-in help

I have created #1064 and added updating doc/org.eclipse.cdt.doc.user/images/cbs_build_settings_tab_cmake.png to the check-list.

ewaterlander · 2025-01-29T16:28:53Z

Hi,
I will address the new comments tomorrow. I don't mind doing it in this PR or a follow up PR.

jld01 · 2025-01-29T19:28:33Z

Could you have a look again? I think the work is done now.

Thanks for the updates, @ewaterlander.

* 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 eclipse-cdt#992

ewaterlander · 2025-01-30T11:59:45Z

Hi @jonahgraham and @betamaxbandit ,

I updated the image and addressed the comments.

ewaterlander · 2025-01-30T12:01:41Z

I squashed and rebased the commit. After rebasing I lost some time, because Eclipse-Committers did not properly refresh the work area, which cause build errors in my environment. :(

jonahgraham · 2025-01-30T14:00:47Z

I squashed and rebased the commit. After rebasing I lost some time, because Eclipse-Committers did not properly refresh the work area, which cause build errors in my environment. :(

That is frustrating - I think the other day I had a fail to refresh properly error, I couldn't reproduce it and I am not sure what happened.

jonahgraham · 2025-01-30T14:02:55Z

Thanks @ewaterlander

jonahgraham approved these changes Jan 23, 2025

View reviewed changes

doc/org.eclipse.cdt.doc.user/src/getting_started/cbs_launchbar.adoc Show resolved Hide resolved

jld01 self-requested a review January 23, 2025 21:17

jld01 reviewed Jan 24, 2025

View reviewed changes

ewaterlander force-pushed the getting_started branch from c429387 to 9526216 Compare January 24, 2025 16:17

ewaterlander force-pushed the getting_started branch from 9526216 to 378d553 Compare January 24, 2025 16:30

betamaxbandit reviewed Jan 29, 2025

View reviewed changes

jonahgraham approved these changes Jan 29, 2025

View reviewed changes

ewaterlander force-pushed the getting_started branch from 6ba2488 to dfcb2fa Compare January 30, 2025 11:56

jonahgraham approved these changes Jan 30, 2025

View reviewed changes

jonahgraham merged commit c8e47b3 into eclipse-cdt:main Jan 30, 2025
5 checks passed

jonahgraham added this to the 12.0.0 M3 milestone Jan 30, 2025

ewaterlander deleted the getting_started branch January 30, 2025 15:31

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Getting Started documentation update. #1056

Getting Started documentation update. #1056

ewaterlander commented Jan 23, 2025

ewaterlander commented Jan 23, 2025

github-actions bot commented Jan 23, 2025 •

edited

Loading

jonahgraham commented Jan 23, 2025

jonahgraham left a comment

jld01 Jan 24, 2025

jld01 Jan 24, 2025

jld01 Jan 24, 2025 •

edited

Loading

jld01 Jan 24, 2025

jld01 Jan 24, 2025

jld01 Jan 24, 2025

jld01 Jan 24, 2025 •

edited

Loading

jonahgraham Jan 26, 2025

jld01 left a comment

ewaterlander commented Jan 24, 2025

ewaterlander commented Jan 27, 2025

ewaterlander commented Jan 29, 2025

betamaxbandit left a comment

betamaxbandit Jan 29, 2025

betamaxbandit Jan 29, 2025

ewaterlander Jan 30, 2025

betamaxbandit Jan 29, 2025

ewaterlander Jan 30, 2025

betamaxbandit Jan 29, 2025

ewaterlander Jan 30, 2025

jonahgraham left a comment

ewaterlander commented Jan 29, 2025

jld01 commented Jan 29, 2025

ewaterlander commented Jan 30, 2025

ewaterlander commented Jan 30, 2025

jonahgraham commented Jan 30, 2025

jonahgraham commented Jan 30, 2025


		== Launch Bar

		CBS projects rely on the LaunchBar. Make sure the launch bar plugin

	CBS projects rely on the LaunchBar. Make sure the launch bar plugin
	Core Build System (CBS) projects rely on the Launch Bar. Make sure the _LaunchBar UI_ feature

		This tutorial describes how to use existing code for Core Build System
		projects.


		image:cbs_empty_cmake_project.png[Empty or Existing CMake Project]

		Then in the New CMake Project wizard deselect Use default location

	Then in the New CMake Project wizard deselect Use default location
	In the New CMake Project wizard deselect Use default location

		=== Using an existing Makefile project

		Create a Makefile project as described in

		In the New Makefile Project wizard deselect Use default location
		and set the location of the existing code, and deselect *Create Hello

		Using existing code is done by creating a new empty project on top of the
		existing code.

Getting Started documentation update. #1056

Getting Started documentation update. #1056

Conversation

ewaterlander commented Jan 23, 2025

ewaterlander commented Jan 23, 2025

github-actions bot commented Jan 23, 2025 • edited Loading

Test Results

jonahgraham commented Jan 23, 2025

jonahgraham left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jld01 Jan 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jld01 Jan 24, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jld01 left a comment

Choose a reason for hiding this comment

ewaterlander commented Jan 24, 2025

ewaterlander commented Jan 27, 2025

ewaterlander commented Jan 29, 2025

betamaxbandit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonahgraham left a comment

Choose a reason for hiding this comment

ewaterlander commented Jan 29, 2025

jld01 commented Jan 29, 2025

ewaterlander commented Jan 30, 2025

ewaterlander commented Jan 30, 2025

jonahgraham commented Jan 30, 2025

jonahgraham commented Jan 30, 2025

github-actions bot commented Jan 23, 2025 •

edited

Loading

jld01 Jan 24, 2025 •

edited

Loading

jld01 Jan 24, 2025 •

edited

Loading