From 4b28dfba4348143338eed6814037089f05262965 Mon Sep 17 00:00:00 2001 From: Jonah Graham Date: Tue, 7 Jan 2025 20:18:01 -0500 Subject: [PATCH] Generate more of the documentation with asciidoc and automate more - Migrate all getting_started from html to adoc - Document (in README.md) notes on migrating html to adoc - Reorganize generation of adoc slightly so that - all directories can be generates at once - output suffix changed to htm so that migrated files exist at the same URL on help.eclipse.org - Add generation to the cleanliness checks to ensure that the html matches adoc - Manage the adoc headers with a script as that is a large section of copy-pasted code on each adoc file (see README + adoc-headers.txt) - Move maven version info to pluginManagement (consistency with other maven plug-ins) - New profile "asciidoc-auto-refresh" which will auto build the files as edited. Prerequisite of #992 --- .github/workflows/build-test.yml | 16 ++ doc/org.eclipse.cdt.doc.user/.gitignore | 4 +- doc/org.eclipse.cdt.doc.user/README.md | 46 ++++ doc/org.eclipse.cdt.doc.user/adoc-headers.txt | 29 +++ doc/org.eclipse.cdt.doc.user/build.properties | 5 +- .../getting_started/cdt_o_tutorial.htm | 50 ----- .../getting_started/cdt_w_basic.htm | 166 -------------- .../getting_started/cdt_w_build.htm | 65 ------ .../getting_started/cdt_w_debug.htm | 132 ----------- .../getting_started/cdt_w_existing_code.htm | 211 ------------------ .../getting_started/cdt_w_import.htm | 148 ------------ .../getting_started/cdt_w_install_cdt.htm | 87 -------- .../getting_started/cdt_w_newcpp.htm | 98 -------- .../getting_started/cdt_w_newmake.htm | 83 ------- .../getting_started/cdt_w_newproj.htm | 120 ---------- .../cdt_w_prepare_workbench.htm | 85 ------- .../getting_started/hw_example.htm | 31 --- .../getting_started/make_example.htm | 27 --- doc/org.eclipse.cdt.doc.user/help.css | 36 +-- doc/org.eclipse.cdt.doc.user/helpadoc.css | 42 ++++ doc/org.eclipse.cdt.doc.user/pom.xml | 59 +++-- .../src/{asciidoc => example}/example.adoc | 26 ++- .../src/getting_started/cdt_o_tutorial.adoc | 50 +++++ .../src/getting_started/cdt_w_basic.adoc | 189 ++++++++++++++++ .../src/getting_started/cdt_w_build.adoc | 85 +++++++ .../src/getting_started/cdt_w_debug.adoc | 147 ++++++++++++ .../getting_started/cdt_w_existing_code.adoc | 180 +++++++++++++++ .../src/getting_started/cdt_w_import.adoc | 171 ++++++++++++++ .../getting_started/cdt_w_install_cdt.adoc | 112 ++++++++++ .../src/getting_started/cdt_w_newcpp.adoc | 108 +++++++++ .../src/getting_started/cdt_w_newmake.adoc | 87 ++++++++ .../src/getting_started/cdt_w_newproj.adoc | 166 ++++++++++++++ .../cdt_w_prepare_workbench.adoc | 66 ++++++ .../src/getting_started/docinfo-footer.htm | 2 + .../src/getting_started/docinfo-header.htm | 1 + .../src/getting_started/hw_example.adoc | 48 ++++ .../src/getting_started/make_example.adoc | 44 ++++ .../new_cmake_proj.adoc | 40 ++-- .../topics_Getting_Started.xml | 2 +- pom.xml | 5 + releng/scripts/do_all_code_cleanups.sh | 1 + releng/scripts/do_generate_asciidoc.sh | 39 ++++ 42 files changed, 1731 insertions(+), 1378 deletions(-) create mode 100644 doc/org.eclipse.cdt.doc.user/adoc-headers.txt delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_import.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_install_cdt.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newcpp.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newmake.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_prepare_workbench.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/hw_example.htm delete mode 100644 doc/org.eclipse.cdt.doc.user/getting_started/make_example.htm create mode 100644 doc/org.eclipse.cdt.doc.user/helpadoc.css rename doc/org.eclipse.cdt.doc.user/src/{asciidoc => example}/example.adoc (52%) create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_o_tutorial.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_basic.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_build.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_debug.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_existing_code.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_import.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_install_cdt.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newcpp.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newmake.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_prepare_workbench.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-footer.htm create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-header.htm create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/hw_example.adoc create mode 100644 doc/org.eclipse.cdt.doc.user/src/getting_started/make_example.adoc rename doc/org.eclipse.cdt.doc.user/src/{asciidoc => getting_started}/new_cmake_proj.adoc (64%) create mode 100755 releng/scripts/do_generate_asciidoc.sh diff --git a/.github/workflows/build-test.yml b/.github/workflows/build-test.yml index 26337be7543..068ed2d7a3e 100644 --- a/.github/workflows/build-test.yml +++ b/.github/workflows/build-test.yml @@ -21,6 +21,8 @@ jobs: - 'dsf/**' - 'debug/**' - 'jtag/**' + docs: + - 'doc/org.eclipse.cdt.doc.user/**' - name: Set up JDK 21 uses: actions/setup-java@v4 with: @@ -64,3 +66,17 @@ jobs: path: | */*/target/surefire-reports/*.xml terminal/plugins/org.eclipse.tm.terminal.test/target/surefire-reports/*.xml + - name: Prepare Docs for upload + if: (success() || failure()) && steps.filter.outputs.docs + run: | + mkdir -p docs/user + cd docs/user + unzip ../../releng/org.eclipse.cdt.repo/target/repository/plugins/org.eclipse.cdt.doc.user_*.jar + - name: Upload Docs + uses: actions/upload-artifact@v4 + if: (success() || failure()) && steps.filter.outputs.docs + with: + name: docs + include-hidden-files: true + path: | + docs/** diff --git a/doc/org.eclipse.cdt.doc.user/.gitignore b/doc/org.eclipse.cdt.doc.user/.gitignore index 7cb3f4e9213..2fddf3a13e9 100644 --- a/doc/org.eclipse.cdt.doc.user/.gitignore +++ b/doc/org.eclipse.cdt.doc.user/.gitignore @@ -1,2 +1,2 @@ -/html/ -/workspace/ +/getting_started/ +/example/ diff --git a/doc/org.eclipse.cdt.doc.user/README.md b/doc/org.eclipse.cdt.doc.user/README.md index a889d071619..13f33da8d7a 100644 --- a/doc/org.eclipse.cdt.doc.user/README.md +++ b/doc/org.eclipse.cdt.doc.user/README.md @@ -10,4 +10,50 @@ 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 +# or to turn on auto-refresh +mvn --define jgit.dirtyWorkingTree-cdtDefault=ignore --projects org.eclipse.cdt:org.eclipse.cdt.doc.user generate-resources -P asciidoc-auto-refresh ``` + +Adding `-DuseSimrelRepo`, and after first run `-o` can speed up target platform resolution speed significantly. + +## 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 +- Remove the original htm file from source control and add it to .gitignore (add whole folder if possible, or individual files if not whole folder is converted) 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/build.properties b/doc/org.eclipse.cdt.doc.user/build.properties index 3f0e0a171b4..349217b3538 100644 --- a/doc/org.eclipse.cdt.doc.user/build.properties +++ b/doc/org.eclipse.cdt.doc.user/build.properties @@ -23,6 +23,8 @@ bin.includes = about.html,\ contexts_CDT_make.xml,\ getting_started/,\ help.css,\ + helpadoc.css,\ + font-awesome/,\ images/,\ plugin.properties,\ plugin.xml,\ @@ -38,8 +40,7 @@ bin.includes = about.html,\ intro/,\ notices.html,\ book.css,\ - index*/,\ - html/ + index*/ bin.excludes = build.properties,\ customBuildCallbacks.xml diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm deleted file mode 100644 index cbacf47c138..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_o_tutorial.htm +++ /dev/null @@ -1,50 +0,0 @@ - - - - - - Tutorials - - - -
-

Getting Started

- -

The following tutorials guide you through the process of using the C/C++ Development Toolkit (CDT) to:

- - -Prepare the Workbench
- -Create a simple application
- -Create a Makefile project
- - -Import an existing project
-Create a C++ file
-Create a makefile
- -Build a project
- - -Debug a project
- - -
-Import C/C++ source into Eclipse
- -Install/update the CDT
- -

An alternative getting started is available on the Wiki at Setting Up Eclipse CDT.

- - - -

Related reference -
- CDT Home
-

-

QNX Software Systems Copyright Statement

-
- - - \ 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 deleted file mode 100644 index e157f3f2474..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_basic.htm +++ /dev/null @@ -1,166 +0,0 @@ - - - - - New CDT Project with generated makefile - Tutorial - - - - -

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:

-
    -
  1. Creating a project
    2. -
  2. Reviewing the code and building the project
    3. -
  3. Running the application
    4. -
-
-

Step 1: Creating a project

-
    -
  1. Select File > New > Project.
    -
    - - Select File > New > Project menu option -


    -

    -
    2. - -
  2. Select the type of project to create. For this tutorial, expand the C++ folder and select C++ Project and click Next.
    -
    - Select project type
    -
    -
    3. -
  3. -

    The C++ Project wizard opens.
    -

    -

    C++ project wizard
    -
    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.

    -
    - - -
      -
    1. In the Project name field, type a name for the project, such as HelloWorld. -


      -

      -
      2. -
    2. 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. -


      -

      -
      3. -
    3. 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.

      -


      -

      -
      4. -
    4. Click Next.
      5. -
    -
    -
    4. - - - -
  4. Specify the Basic Properties for the new project, such as your author, copyright, and source information, then click Next.
    -
    - Basic properties of a project
    -
    -
    5. -
  5. -

    The Select Configurations page displays a list of configurations based on the project type and toolchain(s) selected earlier.
    -
    - Select configurations page
    -
    - 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.
    -
    -

    6. -

  6. Click Finish.
    -

    7. -
-

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.

- -

             New project displayed in the Project Explorer view

-
-
-
-

Step 2: Reviewing the code and building the project

-
    -
  1. 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.
    -
    - C Editor with Outline view
    -
    - 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.
    -
    -

    -
    2. -
  2. Build your project by pressing CTRL+B, or select the project in the Project Explorer view and select Project > Build Project. -

    -


    - NOTE: If a build generates any errors or warnings, you can see those in the Problems view. If you encounter difficulty, see the topics Building C/C++ projects and Before you begin
    - .

    -
    3. -
  3. 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.

    4. -
- -
-
-

Step 3: Running the application

- -

To run your application:

-
    -
  1. Within the C/C++ Perspective, click Run > Run Configurations....


    2. -
  2. Select C/C++ Application.


    3. -
  3. 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). -

    4. -
  4. 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.


    5. - -
  5. You can click the other views to see the information that they contain.
    6. -
- - -
-QNX Software Systems Copyright Statement -
- \ 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 deleted file mode 100644 index dde9e59c20c..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_build.htm +++ /dev/null @@ -1,65 +0,0 @@ - - - - - - Building your 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:

-
    -
  1. In the Project Explorer view, select your project. For the tutorial, you can select the HelloWorld project you created earlier.


    2. -
  2. Click Project > Build Project, or click the build icon 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.



    3. -
  3. 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 in C/C++ Perspective
    -
    4. -
-

Related concepts -
-CDT Projects
-Build overview
-

-

Related tasks -
-Building projects
-

-

Related reference -
-Make Builder page, -C/C++ Properties window
-

-

-Next icon Next: Debugging a project

-

-Previous icon Back: Creating a makefile

-

-QNX Copyright Statement

-
- 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 deleted file mode 100644 index 4697ba53684..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_debug.htm +++ /dev/null @@ -1,132 +0,0 @@ - - - - - - - Debugging your 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:

-
    -
  1. Click the Run > Debug Configurations... menu option.
    -
    -

    The Debug Configurations dialog opens.
    -
    - Debug Configurations dialog
    -
    -

    2. -
  2. Double-click C/C++ Application to create a new launch configuration.
    -
    - C/C++ Application debug 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.
    -
    -

    -
      -
    1. 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.
      -
      -
      2. -
    2. 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.
      -
      -
      3. -
    3. -

      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).
      -
      -

      -
      4. -
    -
    3. -
  3. 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.

    - -
    -

             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.
    -

    -
    -
    4. - -
  4. 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 (Breakpoint) there indicating the breakpoint is set.
    -
    -
    -
    5. -
  5. Click Run > Resume. -
    -
    - Or, you can use the Resume button (Resume) on the toolbar of the Debug view - .
    -
    -
    6. -
  6. When prompted, in the Console view, type a value other than 'm', and press Enter.
    -
    - The breakpoint will be hit.
    -
    -
    7. -
  7. In the Variables view, verify that the variable is not 'm'.
    -
    -
    8. -
  8. Click Run > Resume.
    -
    -
    9. -
  9. When prompted, again type a value other than 'm' in the Console view, and press Enter. -

    The breakpoint will be hit.

    10. -
  10. In the Variables view, verify that the variable is not 'm'.
    -
    -
    11. -
  11. In the Variables view, right-click the input variable, and select Change Value... - and type 'm' between the single quotes and hit OK.
    -
    -
    12. -
  12. Click Run > Resume. -

    The output in the helloworld.exe application window is:  "Thank you. Exiting." -

    13. -
  13. The application terminates and the debug session ends. The Debug perspective remains open.
    14. -
-

To learn more about debugging, see the related debug conceptual topics.

- -

-Back icon Back: Building a project   

- -

Related concepts -
-Debug overview
-Debug information

-

Related tasks -
-Debugging

-

Related reference -
-Debug view
-Debug launch controls
- 

-

-QNX Copyright Statement -

- - \ 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 deleted file mode 100644 index ca040c2624a..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_existing_code.htm +++ /dev/null @@ -1,211 +0,0 @@ - - - - - - How to bring 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 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: -

- -
    -
  1. - 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. -

    - -
    2. - -
  2. - 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. -

  3. Click Finish to exit the Check Out As dialog. -

    - -
  4. 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: -

- -
    -
  1. - 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. -

    - -
  2. Choose Check out into an existing project, and then click - Next. - The IDE displays the Check Out Into dialog: - -
    3. - -
  3. - Select an existing project from the list, and then - click Finish to add the code from CVS to the selected - project. -
    4. -
- - -

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: -
    -
  1. Identify a "root folder" of your source code tree.
    2. -
  2. 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.
    3. -
-

Typically, existing projects will have their own makefiles, so you should create a new Make C/C++ project. For more information see -Creating a project and -Working with C/C++ project files.

- -

To help you to identify a root folder for your project, consider the following guidelines: -

- -

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:

-

-

- -

Related concepts -
-Overview of the CDT
- CDT Projects

-

Related tasks -
-Working with C/C++ project files

-

Related reference -
-Project properties

- -QNX Copyright Statement - -

- - \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_import.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_import.htm deleted file mode 100644 index 5afd41bd604..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_import.htm +++ /dev/null @@ -1,148 +0,0 @@ - - - - - - CDT Importing an Existing Managed Make Project Tutorial - - - - - -

Tutorial: Importing an existing project

- -

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.

-
    -
  1. Select File > New > Project.
    2. -
  2. For this tutorial, expand C/C++ and select C++ project. -


    - The New Project wizard displays. - Click - here to see an illustration (displayed in a separate window).

    -
    3. -
  3. In the Project name field, type a name for the project.
    4. -
  4. 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. -

      - Click - here to see an illustration (displayed in a separate window).

    - -
    5. -
  5. In the Location field, specify the path to the existing files for your project.
    6. -
  6. 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
      • -
    7. -
  7. Make sure a toolchain is selected.
    8. - -
  8. Click Next. -

     

    9. - -
  9. (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.
    10. -
  10. 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.

    - -
    11. -
- -

Step 2: You are now ready to build your project.

-
    -
  1. To build your project, select Project > Build Project. -
    You can also hit the hammer icon build icon on the toolbar to - build the selected project. -
     
    2. -
  2. 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 - here to see an illustration (displayed in a separate window).

      -
      • -
    • 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 build 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.

    -

      - Click - here to see an illustration (displayed in a separate window).


    3. -
  3. 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. -

    Click here to see an illustration (displayed in a separate window).


    - -
    -

    -
    4. -
- -

Step 3: You are now ready to run your application.

-
    -
  1. To run your application within the C/C++ Perspective, click Run > Run Configurations...

    -

    The Run Configurations dialog displays.

    -
  2. To create a run configuration, select C/C++ Application and click the New icon. -
  3. Give your run configuration a name by entering a new name in the Name field at the top. -
  4. 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. -
  5. 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.

    -

    Click - here to see an illustration (displayed in a separate window).

    -
      -
    • 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). -
      • -
    - - -
  6. Click Run to save the run configuration and run it. -

    Click - here to see an illustration (displayed in a separate window).

    -

    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.

    -
-QNX Copyright Statement -
- diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_install_cdt.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_install_cdt.htm deleted file mode 100644 index d8a575c4c7d..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_install_cdt.htm +++ /dev/null @@ -1,87 +0,0 @@ - - - - - - -Updating the CDT - - - - - - - -

Installing and updating the CDT

- -

You can use the Software Updates manager to quickly install or update the CDT directly from the Eclipse workbench using your internet connection.

- -

To obtain the latest CDT features:

-
    -
  1. Select Help > Software Updates > Find and Install. -

    Click here to see an illustration (displayed in a separate window).

    -
    2. - -
  2. In the Feature Updates window, select Search for new features to install and click Next.

    Note: If you want to search for updates on features that you currently have installed, you can select the option Search for updates of the currently installed features, and then follow the steps to update using that method.

    Click here to see an illustration.

    -
    3. - - -
  3. If you have not updated previously, you will have to enter the location of the Eclipse CDT Install site. Click New Remote Site.... -

    Click here to see an illustration.

    -
    4. - -
  4. In the New Update Site dialog box, type the name and URL for the Eclipse update site. -

    Click here to see an illustration.


    5. - -
  5. Click OK.


    6. -
  6. From the Sites to include in search list, select the update site you just created by clicking the appropriate check box, and click Finish. -

    Click here to see an illustration.

    -
    7. - -
  7. The Search Results dialog shows the features available to install from the update site. Expand and select any additional features that you require. De-select any options that do not apply to you.


    8. -
  8. Click Next. -

    Click here to see an illustration.


    -
    9. - -
  9. You must accept the Eclipse.org Software User Agreement to continue installing the CDT update. If you accept the terms, select I accept the terms in the license agreement and then click Next. -

    Click here to see an illustration.

    -
    -

    You can review the summary list of the features you selected to install.


    10. -
  10. Optional: Click Change Location to select the location you would like the updates installed. Typically, this is the directory where you installed Eclipse.


    11. -
  11. Click Finish.

    Click here to see an illustration.

    -
    12. - -
  12. You will now start downloading the CDT components. You will have to verify that you want the features installed by clicking - Install for each feature you selected. -

    Click here to see an illustration.

    -

    Now, you have to restart Eclipse.


    13. - - -
  13. Select Yes to complete the feature installation process. - -

    Click here to see an illustration.

    -
-

Related concepts -
-CDT Overview
-C/C++ Development perspective
- 

- -QNX Copyright Statement

- -
- - \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newcpp.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newcpp.htm deleted file mode 100644 index 3acbf561753..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newcpp.htm +++ /dev/null @@ -1,98 +0,0 @@ - - - - - - - Creating your C++ file - - - - - -

Creating your C++ file

- -

You can begin coding your HelloWorld program. The .cpp file that you -create will be saved in the project folder you just created -Creating a Makefile project.

- -

Files are edited in the C/C++ editor located to the right of -the C/C++ Projects view. The left margin of the C/C++ editor, called the marker -bar, displays icons for items such as bookmarks, breakpoints, and compiler errors and warnings.

- -

For more information about:

- -

To create a C++ file:

-
    -
  1. In the Project Explorer view, right-click the HelloWorld project - folder, and select New > Source File.
    2. -
  2. In the Source file: field, type main.cpp. -
    By default the source folder should be your project folder. -
    The template selected is probably Default C/C++ Source Template. -
    3. -
  3. Click Finish.
    4. -
  4. A Comment template probably appears at the top of an otherwise empty file. - Type the code, exactly as it appears below, in the editor. - Or you can paste it in from this help file. - -
    -#include <iostream>
-using namespace std;
-
-int main () {
-    // Say HelloWorld five times
-    for (int index = 0; index < 5; ++index)
-      cout << "HelloWorld!" << endl;
-    char input = 'i';
-    cout << "To exit, press 'm' then the 'Enter' key." << endl;
-    cin  >> input;
-    while(input != 'm') {
-        cout << "You just entered '" << input << "'. "
-             << "You need to enter 'm' to exit." << endl;
-        cin  >> input;
-    }
-    cout << "Thank you. Exiting." << endl;
-    return 0;
-}
-
    -
    5. - -
  5. Click File > - Save.
    6. -
- -

Your new .cpp file is displayed in the Project Explorer view. Your project now contains main.cpp. Before you -can build your HelloWorld project, you must create a makefile.

- -

- -Next icon Next: Creating your makefile -

- -

-Back icon Back: Creating your project

- -

Related concepts -
-CDT projects
-Project file views
-Coding aids

-

Related tasks -
-Working with C/C++ project files
-Writing code

-

Related reference -
-C/C++ Projects view

- -

-IBM Copyright Statement -

- - diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newmake.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newmake.htm deleted file mode 100644 index 927698d91b7..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newmake.htm +++ /dev/null @@ -1,83 +0,0 @@ - - - - - - - Creating your makefile - - - - - - -

Creating a makefile

- -

For the purpose of this tutorial, you were instructed to create a C++ Project which requires you to create a makefile.

- -

To create a makefile:

-
    -
  1. In the Project Explorer view, right-click the HelloWorld project - folder and select New > File.
    2. -
  2. In the File name box, type makefile.
    3. -
  3. Click Finish.
    4. -
  4. Type the gnu make instructions below in the editor. Lines are - indented with tab characters, not with spaces. - -
    -

    -
    - all: hello.exe
    -
    - clean:
    -    rm main.o hello.exe
    -
    - hello.exe: main.o
    -    g++ -g -o hello main.o
    -
    - main.o:
    -    g++ -c -g main.cpp
    - 

    -
    -
    5. -
  5. Click File > - Save.
- -

Your new makefile, along with your main.cpp file are -displayed in the Project Explorer view. Your project now -contains main.cpp and makefile. You can now build your HelloWorld project.

- - -

NEW Click here to see an illustration.

- -

- - Next icon - - Next: Building your project -

-

- - -Back icon Back: Creating your C++ file

-

Related concepts -
-Project
-Code entry

-

Related tasks -
-Working with C/C++ project files
-Writing code

-

Related reference -
-C/C++ Projects view

- -

-IBM Copyright Statement -

- - \ No newline at end of file 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 deleted file mode 100644 index 48dec435d7d..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_newproj.htm +++ /dev/null @@ -1,120 +0,0 @@ - - - - - - Creating your project - - - - - -

Creating a Makefile project

- -

-This tutorial describes the process of creating a new C++ project that includes a makefile, and debugging the program.

-

You need to create a project to contain your source code and related files. A project has an associated builder -that can incrementally compile source files as they are changed.

- -

To create a project:

- -
    -
  1. Select File > New > Project. -


    When you create a new project, you are required to specify the project type. This project type will determine the toolchain, data, and tabs that the CDT uses/displays.


    -
  2. Select the type of project to create. For this tutorial, expand the C/C++ folder and select C++ Project. -

    The C++ Project wizard opens. Click here to see an illustration.


    -

    By default, the CDT filters the Toolchain and Project types that currently display in those lists are based on the language support for the C++ Project wizard you selected for this tutorial.


    -
  3. In the Project name field, type HelloWorld. -
  4. Leave the Use Default Location option selected. -


    Next, you want to select the type of project to create. In the New CDT Project Wizard, you can choose from the following project types:

    -
      -
    • Executable - Provides an executable application. This project type folder contains three templates.

      -
        -
      • Hello World C++ Example provides a simple C++ Hello World application with main(). -
      • Hello World ANSI C Example provides a simple C Hello World application with main(). -
      • Empty Project provides a single source project folder that contains no files. -

        After you select this template, the result is a project with only the meta-data files required for the project type. - You are expected to provide source files for the project's target.

        -
      -

      The makefile for the Executable project type is automatically created by the CDT.

      -

       

      -
    • Shared Library - An executable module that is compiled and linked separately. When you create a project that uses a shared library (libxx.so), you define your shared library's project as a Project Reference for your application. For this project type, the CDT combines object files together and joins them so they're relocatable and can be shared by many processes. Shared libraries are named using the format - libxx.so.version, where -version is a number with a default of 1. The -libxx.so file usually is a symbolic link to the -latest version. The makefile for this project type is automatically created by the CDT. -
    • Static Library - A collection of object files that you can link into another application (libxx.a). The CDT combines object files (i.e. *.o) -into an archive (*.a) that is directly linked into an -executable. The makefile for this project type is automatically created by the CDT. -
    • Makefile Project - Creates an empty project without the meta-data files. This selection is useful for importing and modifying existing makefile-based projects; a new makefile is not created for this project type. -
    - -

    By default, the CDT filters the Toolchain and Project types that currently display in those lists based on the language support for the C++ Project wizard you selected for this tutorial. -

     

    -
  5. From the Project types list, expand Makefile project and select Empty Project. -This project lets you enter the source file and the makefile yourself. - -
  6. 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. -

    - -
    7. -
  7. Click Next. -
  8. (Optional) On the Select Configurations page, Click Advanced Settings. -
      -
    • Expand C/C++Build > Settings. Click the Binary Parsers tab. -


      Click here to see an illustration.


      -

      -
      • -
    • In the Binary Parser list, select the error parser that is appropriate for your platform. -Other project settings can be modified here as well. The default selection is probably OK. - -
      -

      To ensure the accuracy of the C/C++ Projects view and the ability to successfully -run and debug your programs, selecting the correct parser is important. After -you select the correct parser for your development environment and build your - project, you can view the components of the .o file in the C/C++ Projects -view. You can also view the contents of the .o file in the C/C++ editor. -


      Click OK to close the Project Properties window.
      • -
    - -
  9. Click Finish.
    10. -
  10. If a message box prompts you to change perspectives, click Yes. -
    11. -
- -

Your new project displays in the Project Explorer view. -Your project is empty because you have not yet created -files for your project. -You may see an error since there is nothing to build yet for your project. -You can now start writing the code for your HelloWorld -program.

- -

Tip: You can view and modify the properties of your -HelloWorld project at any time by right-clicking on the project in the Project Explorer -view and clicking Properties.

Next Icon -Next: Creating your C++ file

For more information -about:

Related concepts
CDT overview
-CDT projects
Project file views -

Related tasks
Working with C/C++ project files

Related reference
C/C++ Projects view

- -

QNX Copyright Statement

- -
- \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_prepare_workbench.htm b/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_prepare_workbench.htm deleted file mode 100644 index 5bc8fdbe01d..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/cdt_w_prepare_workbench.htm +++ /dev/null @@ -1,85 +0,0 @@ - - - - - -Preparing the Workbench - - - - - -
-

Preparing the Workbench

- -

This tutorial will get you started using the C/C++ Development - Toolkit (CDT) in the Workbench.

-

First, you will verify that the workbench is properly - configured for C/C++ development. It is assumed that:

- - -

Setting the global editor operations and appearance

- -

- The main place to configure global editor-related preferences is the - - command linkGeneral > Editors - preference pages (also accessible through the Window - > Preferences menu item) -

-

Setting the C/C++ editor operations and appearance

-

- C/C++-specific editor preferences are under - command linkC/C++ > Editor. - They include the following: -

- - -

- Related reference
- C/C++ Editor - Preferences -

-

- Red Hat Copyright Statement
- IBM Copyright Statement -

-
- - diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/hw_example.htm b/doc/org.eclipse.cdt.doc.user/getting_started/hw_example.htm deleted file mode 100644 index f5abc5c17bd..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/hw_example.htm +++ /dev/null @@ -1,31 +0,0 @@ - - - - - - C++ Hello World example - - -
-Copy the code below and paste it into the main.cpp file in the Editor view:

- -
-#include <iostream>
-#include <string>
-using namespace std;
-
-int main()
-{
-	string yourName;
-
-	cout << "Type your name: ";
-	cin  >> yourName;
-	cout << "Hello " + yourName << endl;
-
-	return 0;
-}
-
-
- -
- \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/getting_started/make_example.htm b/doc/org.eclipse.cdt.doc.user/getting_started/make_example.htm deleted file mode 100644 index 86a51a138a0..00000000000 --- a/doc/org.eclipse.cdt.doc.user/getting_started/make_example.htm +++ /dev/null @@ -1,27 +0,0 @@ - - - - - - C++ Makefile example - - -
-

Copy the script below and paste it into the makefile file in the Editor view:

- -
-all: hello
-
-clean:
-	-rm main.o hello.exe hello
-
-hello: main.o
-	g++ -g -o hello main.o
-
-main.o: main.cpp
-	g++ -c -g main.cpp
-
-
- -
- \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/help.css b/doc/org.eclipse.cdt.doc.user/help.css index 37cc249967a..9480829fd21 100644 --- a/doc/org.eclipse.cdt.doc.user/help.css +++ b/doc/org.eclipse.cdt.doc.user/help.css @@ -17,7 +17,7 @@ h1 { font-size: 18pt; margin-top: 5; margin-bottom: 1 } h2 { font-size: 14pt; margin-top: 25; margin-bottom: 3 } h3 { font-size: 11pt; margin-top: 20; margin-bottom: 3 } h4 { font-size: 10pt; margin-top: 20; margin-bottom: 3; font-style: italic } -h5 { font size: 13.5pt; } +h5 { font-size: 13.5pt; } p { font-size: 12pt; } pre { margin-left: 6; font-size: 9pt } @@ -60,37 +60,3 @@ div.linux {display:none;} .bold {font-weight:600;} .linethrough {text-decoration: line-through;} .underline {text-decoration: underline;} - -/* AsciiDoc support based on Asciidoctor default stylesheet | MIT License | http://asciidoctor.org (#873) */ -p.tableblock { margin: 0 } -table.tableblock tr th, table.tableblock tr td { padding: 0.3em } -table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dedede } -table.grid-all>thead>tr>.tableblock, table.grid-all>tbody>tr>.tableblock { border-width: 0 1px 1px 0 } -table.grid-all>tfoot>tr>.tableblock { border-width: 1px 1px 0 0 } -table.grid-cols>*>tr>.tableblock { border-width: 0 1px 0 0 } -table.grid-rows>thead>tr>.tableblock, table.grid-rows>tbody>tr>.tableblock { border-width: 0 0 1px 0 } -table.grid-rows>tfoot>tr>.tableblock { border-width: 1px 0 0 0 } -table.grid-all>*>tr>.tableblock:last-child, table.grid-cols>*>tr>.tableblock:last-child { border-right-width: 0 } -table.grid-all>tbody>tr:last-child>.tableblock, table.grid-all>thead:last-child>tr>.tableblock, table.grid-rows>tbody>tr:last-child>.tableblock, table.grid-rows>thead:last-child>tr>.tableblock { border-bottom-width: 0 } -table.frame-all { border-width: 1px } -table.frame-sides { border-width: 0 1px } -table.frame-topbot { border-width: 1px 0 } -th.halign-left, td.halign-left { text-align: left } -th.halign-right, td.halign-right { text-align: right } -th.halign-center, td.halign-center { text-align: center } -th.valign-top, td.valign-top { vertical-align: top } -th.valign-bottom, td.valign-bottom { vertical-align: bottom } -th.valign-middle, td.valign-middle { vertical-align: middle } -div.listingblock pre { padding: 0.7em } -.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} -.admonitionblock>table td.icon{text-align:center;width:80px} -.admonitionblock>table td.icon img{max-width:initial} -.admonitionblock>table td.icon .title{font-weight:bold;text-transform:uppercase} -.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8} -.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} -.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} -.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c} -.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} -.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900} -.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400} -.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000} diff --git a/doc/org.eclipse.cdt.doc.user/helpadoc.css b/doc/org.eclipse.cdt.doc.user/helpadoc.css new file mode 100644 index 00000000000..7b895b7f4a0 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/helpadoc.css @@ -0,0 +1,42 @@ +/* AsciiDoc support based on Asciidoctor default stylesheet combined with help.css to match Eclipse Help look and feel | MIT License | http://asciidoctor.org (#873) */ +/* Additional entries can be added here as more parts of asciidoc are used */ + +@import "./help.css"; + +/* The original help code in CDT relied heavily on
to add a bit of +vertical space and had margins set to 0 most places. So for the adoc +version we do it with CSS instead. */ +ol li p { margin-top: 0; margin-bottom: 0.5em } + +p.tableblock { margin: 0 } +table.tableblock tr th, table.tableblock tr td { padding: 0.3em } +table.tableblock, th.tableblock, td.tableblock { border: 0 solid #dedede } +table.grid-all>thead>tr>.tableblock, table.grid-all>tbody>tr>.tableblock { border-width: 0 1px 1px 0 } +table.grid-all>tfoot>tr>.tableblock { border-width: 1px 1px 0 0 } +table.grid-cols>*>tr>.tableblock { border-width: 0 1px 0 0 } +table.grid-rows>thead>tr>.tableblock, table.grid-rows>tbody>tr>.tableblock { border-width: 0 0 1px 0 } +table.grid-rows>tfoot>tr>.tableblock { border-width: 1px 0 0 0 } +table.grid-all>*>tr>.tableblock:last-child, table.grid-cols>*>tr>.tableblock:last-child { border-right-width: 0 } +table.grid-all>tbody>tr:last-child>.tableblock, table.grid-all>thead:last-child>tr>.tableblock, table.grid-rows>tbody>tr:last-child>.tableblock, table.grid-rows>thead:last-child>tr>.tableblock { border-bottom-width: 0 } +table.frame-all { border-width: 1px } +table.frame-sides { border-width: 0 1px } +table.frame-topbot { border-width: 1px 0 } +th.halign-left, td.halign-left { text-align: left } +th.halign-right, td.halign-right { text-align: right } +th.halign-center, td.halign-center { text-align: center } +th.valign-top, td.valign-top { vertical-align: top } +th.valign-bottom, td.valign-bottom { vertical-align: bottom } +th.valign-middle, td.valign-middle { vertical-align: middle } +div.listingblock pre { padding: 0.7em } +.admonitionblock>table{border-collapse:separate;border:0;background:none;width:100%} +.admonitionblock>table td.icon{text-align:center;width:80px} +.admonitionblock>table td.icon img{max-width:initial} +.admonitionblock>table td.icon .title{font-weight:bold;text-transform:uppercase} +.admonitionblock>table td.content{padding-left:1.125em;padding-right:1.25em;border-left:1px solid #ddddd8} +.admonitionblock>table td.content>:last-child>:last-child{margin-bottom:0} +.admonitionblock td.icon [class^="fa icon-"]{font-size:2.5em;text-shadow:1px 1px 2px rgba(0,0,0,.5);cursor:default} +.admonitionblock td.icon .icon-note:before{content:"\f05a";color:#19407c} +.admonitionblock td.icon .icon-tip:before{content:"\f0eb";text-shadow:1px 1px 2px rgba(155,155,0,.8);color:#111} +.admonitionblock td.icon .icon-warning:before{content:"\f071";color:#bf6900} +.admonitionblock td.icon .icon-caution:before{content:"\f06d";color:#bf3400} +.admonitionblock td.icon .icon-important:before{content:"\f06a";color:#bf0000} diff --git a/doc/org.eclipse.cdt.doc.user/pom.xml b/doc/org.eclipse.cdt.doc.user/pom.xml index de8cb07bc8a..183d4f36c05 100644 --- a/doc/org.eclipse.cdt.doc.user/pom.xml +++ b/doc/org.eclipse.cdt.doc.user/pom.xml @@ -43,26 +43,37 @@ org.asciidoctor asciidoctor-maven-plugin - 3.1.1 + + ${project.basedir}/src + ${project.basedir} + true + true + + font + false + + ../font-awesome/css + ../images + + + coderay + style + ../../helpadoc.css + macro + + .htm + + - adoc-to-html + generate-online-help-from-asciidoc generate-resources process-asciidoc - - ${project.basedir}/html - - font - ../images - - - coderay - ../help.css - macro - - @@ -70,6 +81,26 @@ + + asciidoc-auto-refresh + + + + org.asciidoctor + asciidoctor-maven-plugin + + + generate-online-help-from-asciidoc-auto-refresh + generate-resources + + auto-refresh + + + + + + + build-doc diff --git a/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc b/doc/org.eclipse.cdt.doc.user/src/example/example.adoc similarity index 52% rename from doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc rename to doc/org.eclipse.cdt.doc.user/src/example/example.adoc index 3613c42051d..72d88c55251 100644 --- a/doc/org.eclipse.cdt.doc.user/src/asciidoc/example.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/example/example.adoc @@ -1,16 +1,16 @@ //// -Copyright (c) 2024 John Dallaway and others +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 - -Contributors: - John Dallaway - initial example AsciiDoc content (#873) //// +// pull in shared headers, footers, etc +:docinfo: shared + // support image rendering and table of contents within GitHub ifdef::env-github[] :imagesdir: ../../images @@ -18,6 +18,16 @@ ifdef::env-github[] :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 + = Example document toc::[] @@ -63,3 +73,11 @@ int main (int argc, char* argv[]) { } ---- + +== Makefiles + +*TODO*: How to handle tabs in makefiles? Without tabs Makefile code samples cannot be copied and pasted successfully. + +== See also + +See also the README.md at the root of this bundle as it has additional help on using AsciiDoc. diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_o_tutorial.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_o_tutorial.adoc new file mode 100644 index 00000000000..85a43dc2e69 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_o_tutorial.adoc @@ -0,0 +1,50 @@ +//// +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 + +== Getting Started + +The following tutorials guide you through the process of using the C/{cpp} +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_import.adoc[Import an existing project] +* xref:cdt_w_newcpp.adoc[Create a {cpp} file] +* xref:cdt_w_newmake.adoc[Create a makefile] +* xref:cdt_w_build.adoc[Build a project] +* xref:cdt_w_debug.adoc[Debug a project] +* xref:cdt_w_existing_code.adoc[Import C/{cpp} source into Eclipse] +* xref:cdt_w_install_cdt.adoc[Install/update the CDT] + +image:ngref.gif[Related reference] + +* xref:../concepts/cdt_o_home.adoc[CDT Home] diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_basic.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_basic.adoc new file mode 100644 index 00000000000..cacab2b2318 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_basic.adoc @@ -0,0 +1,189 @@ +//// +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 + +== 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 {cpp} +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: + +. link:#cdt_create[Creating a project] +. link:#cdt_build[Reviewing the code and building the project] +. link:#cdt_running[Running the application] + +''''' + +=== Step 1: [[cdt_create]]Creating a project + +. Select *File > New > Project*. + + +image:cdt_w_basic02.png[Select File > New > Project menu +option,width=591,height=183] ++ +. Select the type of project to create. For this tutorial, expand the +*{cpp}* folder and select *{cpp} Project* and click *Next*. + + +image:cdt_w_basic03a.png[Select project +type,width=525,height=500] + + +. The *{cpp} Project* wizard opens. ++ +image:cdt_w_basic04.png[{cpp} project +wizard,width=525,height=576] + + +By default, the CDT filters the *Toolchain* and *Project types* that it +displays in those lists based on the language support for the {cpp} +Project wizard you selected for this tutorial. ++ +[loweralpha] +.. 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 {cpp} Project*. This project type provides a simple Hello World +application in {cpp}, 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*. + + +image:cdt_w_basic06a.png[Basic properties of a +project,width=525,height=576] + + +. The *Select Configurations* page displays a list of configurations +based on the project type and toolchain(s) selected earlier. + + +image:cdt_w_basic07.png[Select configurations +page,width=525,height=576] + + +*OPTIONAL*: If you want to change the default project settings, click +*Advanced Setting* to open the +xref:../reference/cdt_u_prop_all.adoc[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 *{cpp} 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/{cpp} 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 +xref:../reference/cdt_u_project_explorer_view.adoc[Project Explorer] +view. + +image:cdt_w_basic12.png[New project displayed in +the Project Explorer view,width=423,height=283] + +''''' + +=== Step 2: [[cdt_build]]Reviewing the code and building the project + +. From the *Project Explorer* view, double-click the .cpp file created +for your project, for example, [.typewriter]#HelloWorld.cpp#. You'll +find it within the project "[.typewriter]#src#" folder. ++ +This file opens in a default editor. It contains {cpp} template code for +the Hello World example project you selected earlier. In addition, the +xref:../reference/cdt_u_outline_view.adoc[Outline] view has also been +populated with objects created from your code. + + +image:cdt_w_basic13.png[C Editor with Outline +view,width=731,height=333] + + +*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*. ++ +*NOTE:* If a build generates any errors or warnings, you can see those +in the xref:../reference/cdt_u_problems_view.adoc[Problems] view. If you +encounter difficulty, see the topics +xref:../concepts/cdt_c_build_over.adoc[Building C/{cpp} projects] and +xref:../concepts/cdt_c_before_you_begin.adoc[Before you begin] +. +. Read through the build messages in the +xref:../reference/cdt_u_console_view.adoc[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: [[cdt_running]]Running the application + +To run your application: + +. Within the C/{cpp} Perspective, click *Run > Run Configurations...*. ++ +. Select *C/{cpp} 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. + diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_build.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_build.adoc new file mode 100644 index 00000000000..8c9bfda2600 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_build.adoc @@ -0,0 +1,85 @@ +//// +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 + +The make output and build progress information displays in the +xref:../reference/cdt_u_console_view.adoc[Console] view. The +xref:../reference/cdt_u_make_targets_view.adoc[Make Targets] view +displays makefile actions, and the +xref:../reference/cdt_u_problems_view.adoc[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 +image:hammer-icon.png[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*. + + +image:cdt_w_newmake03.png[Console view in C/{cpp} +Perspective,width=842,height=633] + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_projects.adoc[CDT Projects] +* xref:../concepts/cdt_c_build_over.adoc[Build overview] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_build_task.adoc[Building projects] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_u_newproj_buildset.adoc[Make Builder page, +C/{cpp} Properties window] + +xref:cdt_w_debug.adoc[image:ngnext.gif[Next +icon,width=16,height=16]] *xref:cdt_w_debug.adoc[Next: Debugging a +project]* + +xref:cdt_w_newmake.adoc[image:ngback.gif[Previous +icon,width=16,height=16]] *xref:cdt_w_newmake.adoc[Back: Creating a +makefile]* diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_debug.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_debug.adoc new file mode 100644 index 00000000000..51c944c443c --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_debug.adoc @@ -0,0 +1,147 @@ +//// +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 + +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 *Debug* *Configurations* dialog opens. + + +image:cdt_w_debug_configurations_01.png[Debug Configurations +dialog,width=873,height=662] + + +. Double-click *C/{cpp} Application* to create a new launch +configuration. + + +image:cdt_w_debug_configurations_02.png[C/{cpp} Application +debug configuration,width=763,height=601] + + ++ +If a project is selected in the +xref:../reference/cdt_u_project_explorer_view.adoc[Project Explorer] view +the following data is automatically entered, take a moment to verify its +accuracy or change as needed. + + +[loweralpha] +.. 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/{cpp} 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 "[.typewriter]#[Debugger]: No debugger +available#", select the *Debugger* tab and choose a valid debugger for +your platform (e.g. [.typewriter]#gdb/mi#). + + +. Click *Debug*. + + +You may be prompted to switch to the *Debug* perspective. Click *Yes* ++ +The *Debug* perspective appears with the [.typewriter]#helloworld.exe# +application window open. The C/{cpp} editor repositions in the +perspective. ++ +*NOTE:* If you see the error "[.typewriter]#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 [.typewriter]#main.cpp# window, double-click +to set a breakpoint on: [.typewriter]#cout {lt}{lt} "You just entered"# + + +You'll see a blue circle +(image:icon_breakpoint_obj.gif[Breakpoint,width=16,height=16]) +there indicating the breakpoint is set. + + +. Click *Run > Resume*. + + +Or, you can use the *Resume* button +(image:icon_db_resume.png[Resume,width=19,height=14]) 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 +xref:../reference/cdt_u_console_view.adoc[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 [.typewriter]#helloworld.exe# application window is: +"[.typewriter]#Thank you. Exiting.#" +. The application terminates and the debug session ends. The *Debug* +perspective remains open. + +To learn more about debugging, see the related debug conceptual topics. + +xref:cdt_w_build.adoc[image:ngback.gif[Back +icon,width=16,height=16]] *xref:cdt_w_build.adoc[Back: Building a +project]* + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_over_dbg.adoc[Debug overview] +* xref:../concepts/cdt_c_dbg_info.adoc[Debug information] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_debug.adoc[Debugging] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_u_dbg_view.adoc[Debug view] +* xref:../reference/cdt_u_dbg_view.adoc[Debug launch controls] + diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_existing_code.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_existing_code.adoc new file mode 100644 index 00000000000..00e53e0e602 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_existing_code.adoc @@ -0,0 +1,180 @@ +//// +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 + +== Importing your C/{cpp} 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/{cpp} 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 {cpp} project for the folder. For more +information, see xref:../tasks/cdt_t_proj_new.adoc[Creating a project], +xref:../tasks/cdt_t_proj_new_with_template.adoc[Creating a project via a +project template] and xref:../tasks/cdt_o_proj_files.adoc[Working with +C/{cpp} 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/{cpp} project +* existing C/{cpp} code that isn't part of a project +* existing C/{cpp} code that needs to be added to an existing project + +==== Importing a C/{cpp} project from CVS + +To check out an existing C/{cpp} 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/{cpp} code from CVS + +To check out existing C/{cpp} 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/{cpp} 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/{cpp} code into an existing project + +To import a directory full of C/{cpp} 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/{cpp} 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/{cpp} project. For more information see +xref:../tasks/cdt_t_proj_new.adoc[Creating a project] and +xref:../tasks/cdt_o_proj_files.adoc[Working with C/{cpp} project files]. + +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/{cpp} 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/{cpp} source file system + +Another approach would be to create a C/{cpp} 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/{cpp} +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. + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_over_cdt.adoc[Overview of the CDT] +* xref:../concepts/cdt_c_projects.adoc[CDT Projects] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_proj_files.adoc[Working with C/{cpp} project files] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_o_proj_prop_pages.adoc[Project properties] diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_import.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_import.adoc new file mode 100644 index 00000000000..fdc9342e86e --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_import.adoc @@ -0,0 +1,171 @@ +//// +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 + +== Tutorial: Importing an existing project + +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/{cpp}* and select *{cpp} project*. ++ +The *New Project* wizard displays. + +image:cdt_w_import02.png[] ++ +. 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`. + +image:cdt_w_importBrandon01.png[] +. 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 {cpp} 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. + +image:cdt_w_viewMenu.png[] ++ +* In the *Available Customizations* window, on the *Filters* tab, +uncheck ".* resources." + +image:cdt_w_viewMenuFilters.png[] ++ +* The formerly hidden 'dot' files are now shown in the *Project +Explorer*. + +image:cdt_w_viewMenuFilters2.png[] ++ +* 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 image:hammer-icon.png[build +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/{cpp} 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`. + +image:cdt_w_importBrandon02.png[] ++ +* 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 +image:hammer-icon.png[build 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. + +image:cdt_w_importBrandon03.png[] ++ +. 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 {cpp} 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. + +image:cdt_w_indexer.png[] ++ + +Step 3: You are now ready to run your application. + +. To run your application within the C/{cpp} Perspective, click *Run > Run +Configurations...* ++ +The *Run Configurations* dialog displays. +. To create a run configuration, select *C/{cpp} 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/{cpp} 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. + +image:cdt_w_importBrandon04run.png[] ++ +* 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. + +image:cdt_w_importBrandon04run2.png[] ++ +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. \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_install_cdt.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_install_cdt.adoc new file mode 100644 index 00000000000..f05444f1e32 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_install_cdt.adoc @@ -0,0 +1,112 @@ +//// +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 + +== Installing and updating the CDT + +You can use the Software Updates manager to quickly install or update +the CDT directly from the Eclipse workbench using your internet +connection. + +To obtain the latest CDT features: + +. Select *Help > Software Updates > Find and Install*. ++ +image:cdt_update_find-install.png[] ++ +. In the *Feature Updates* window, select *Search for new features to +install* and click *Next*. ++ +Note: If you want to search for updates on features that you currently +have installed, you can select the option *Search for updates of the +currently installed features*, and then follow the steps to update using +that method. ++ +image:cdt_update_install_new.png[] ++ +. If you have not updated previously, you will have to enter the +location of the Eclipse CDT Install site. Click *New Remote Site...*. ++ +image:cdt_update_install_sites.png[] ++ +. In the New Update Site dialog box, type the name and URL for the +Eclipse update site. ++ +image:cdt_update_install_new_sites.png[] ++ +. Click *OK*. ++ +. From the *Sites to include in search* list, select the update site you +just created by clicking the appropriate check box, and click *Finish*. ++ +image:cdt_update_install_cdt_site.png[] ++ +. The Search Results dialog shows the features available to install from +the update site. Expand and select any additional features that you +require. De-select any options that do not apply to you. ++ +. Click *Next*. ++ +image:cdt_update_search_results.png[] ++ +. You must accept the Eclipse.org Software User Agreement to continue +installing the CDT update. If you accept the terms, select *I accept the +terms in the license agreement* and then click *Next*. ++ +image:cdt_update_license_agreement.png[] ++ ++ +You can review the summary list of the features you selected to +install. ++ +. Optional: Click *Change Location* to select the location you would +like the updates installed. Typically, this is the directory where you +installed Eclipse. ++ +. Click *Finish*. ++ +image:cdt_update_location.png[] ++ +. You will now start downloading the CDT components. You will have to +verify that you want the features installed by clicking *Install* for +each feature you selected. ++ +image:cdt_update_jar_verification.png[] ++ ++ +Now, you have to restart Eclipse. ++ +. Select *Yes* to complete the feature installation process. ++ +image:cdt_restart.png[] + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_over_cdt.adoc[CDT Overview] +* xref:../concepts/cdt_c_perspectives.adoc[C/{cpp} Development perspective] diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newcpp.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newcpp.adoc new file mode 100644 index 00000000000..97801f3e0e3 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newcpp.adoc @@ -0,0 +1,108 @@ +//// +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 + +== Creating your {cpp} file + +You can begin coding your HelloWorld program. The .cpp file that you +create will be saved in the project folder you just created +xref:cdt_w_newproj.adoc[Creating a Makefile project]. + +Files are edited in the C/{cpp} editor located to the right of the C/{cpp} +Projects view. The left margin of the C/{cpp} editor, called the marker +bar, displays icons for items such as bookmarks, breakpoints, and +compiler errors and warnings. + +For more information about: + +* The editor area and marker bar, see *Workbench User Guide > Reference +> User interface information > Views and editors > Editor area* +* The marker bar icons, see *Workbench User Guide > Reference > User +interface information > Icons and buttons > Editor area marker bar* + +To create a {cpp} file: + +. In the *Project Explorer* view, right-click the *HelloWorld* project +folder, and select *New > Source File*. +. In the *Source file:* field, type *main.cpp*. +By default the source folder should be your project folder. +The template selected is probably ``Default C/{cpp} Source Template.'' +. Click *Finish*. +. A Comment template probably appears at the top of an otherwise empty +file. Type the code, exactly as it appears below, in the editor. Or you +can paste it in from this help file. ++ +.... +#include +using namespace std; + +int main () { + // Say HelloWorld five times + for (int index = 0; index < 5; ++index) + cout << "HelloWorld!" << endl; + char input = 'i'; + cout << "To exit, press 'm' then the 'Enter' key." << endl; + cin >> input; + while(input != 'm') { + cout << "You just entered '" << input << "'. " + << "You need to enter 'm' to exit." << endl; + cin >> input; + } + cout << "Thank you. Exiting." << endl; + return 0; +} +.... +. Click *File > Save*. + +Your new .cpp file is displayed in the *Project Explorer* view. Your +project now contains main.cpp. Before you can build your HelloWorld +project, you must create a makefile. + +xref:cdt_w_newmake.adoc[image:ngnext.gif[Next +icon,width=16,height=16]] *xref:cdt_w_newmake.adoc[Next: Creating your +makefile]* + +xref:cdt_w_newproj.adoc[image:ngback.gif[Back +icon,width=16,height=16]] *xref:cdt_w_newproj.adoc[Back: Creating your +project]* + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_projects.adoc[CDT projects] +* xref:../concepts/cdt_c_proj_file_views.adoc[Project file views] +* xref:../concepts/cdt_o_code_entry.adoc[Coding aids] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_proj_files.adoc[Working with C/{cpp} project files] +* xref:../tasks/cdt_o_write_code.adoc[Writing code] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_o_proj_prop_pages.adoc[C/{cpp} Projects view] diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newmake.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newmake.adoc new file mode 100644 index 00000000000..2be00f049c4 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newmake.adoc @@ -0,0 +1,87 @@ +//// +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 + +== Creating a makefile + +For the purpose of this tutorial, you were instructed to create a {cpp} +Project which requires you to create a makefile. + +To create a makefile: + +. In the *Project Explorer* view, right-click the *HelloWorld* project +folder and select *New > File*. +. In the *File name* box, type *makefile*. +. Click *Finish*. +. Type the gnu make instructions below in the editor. Lines are indented +with tab characters, not with spaces. ++ +[source,makefile] +---- +all: hello.exe + +# NOTE: ensure the indented lines are indented with tab characters and not space. +clean: + rm main.o hello.exe + +hello.exe: main.o + g++ -g -o hello main.o + +main.o: + g++ -c -g main.cpp +---- +. Click *File > Save*. + +Your new makefile, along with your main.cpp file are displayed in the +Project Explorer view. Your project now contains main.cpp and makefile. +You can now build your HelloWorld project. + +image:cdt_w_newmake02.png[] + +xref:cdt_w_build.adoc[image:ngnext.gif[Next +icon,width=16,height=16]] *xref:cdt_w_build.adoc[Next: Building your +project]* + +xref:cdt_w_newcpp.adoc[image:ngback.gif[Back +icon,width=16,height=16]] *xref:cdt_w_newcpp.adoc[Back: Creating your {cpp} +file]* + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_projects.adoc[Project] +* xref:../concepts/cdt_o_code_entry.adoc[Code entry] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_proj_files.adoc[Working with C/{cpp} project files] +* xref:../tasks/cdt_o_write_code.adoc[Writing code] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_o_proj_prop_pages.adoc[C/{cpp} Projects view] 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 new file mode 100644 index 00000000000..c63151aa4c7 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_newproj.adoc @@ -0,0 +1,166 @@ +//// +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 + +== Creating a Makefile project + +This tutorial describes the process of creating a new {cpp} project that +includes a makefile, and debugging the program. + +You need to create a project to contain your source code and related +files. A project has an associated builder that can incrementally +compile source files as they are changed. + +To create a project: + +. Select *File > New > Project*. ++ +When you create a new project, you are required to specify the project +type. This project type will determine the toolchain, data, and tabs +that the CDT uses/displays. ++ +. Select the type of project to create. For this tutorial, expand the +*C/{cpp}* folder and select *{cpp} Project*. ++ +The *{cpp} Project* wizard opens. javascript:void(0)[Click here to see an +illustration.] ++ +By default, the CDT filters the *Toolchain* and *Project types* that +currently display in those lists are based on the language support for +the {cpp} Project wizard you selected for this tutorial. ++ +. In the *Project name* field, type HelloWorld. +. Leave the *Use Default Location* option selected. ++ +Next, you want to select the type of project to create. In the New CDT +Project Wizard, you can choose from the following project types: +* *Executable* - Provides an executable application. This project type +folder contains three templates. +** *Hello World {cpp} Example* provides a simple {cpp} Hello World +application with main(). +** *Hello World ANSI C Example* provides a simple C Hello World +application with main(). +** *Empty Project* provides a single source project folder that contains +no files. + + +After you select this template, the result is a project with only the +meta-data files required for the project type. You are expected to +provide source files for the project's target. + + +The makefile for the *Executable* project type is automatically created +by the CDT. + + + +* *Shared Library* - An executable module that is compiled and linked +separately. When you create a project that uses a shared library +(libxx.so), you define your shared library's project as a Project +Reference for your application. For this project type, the CDT combines +object files together and joins them so they're relocatable and can be +shared by many processes. Shared libraries are named using the format +libxx.so.`version`, where `version` is a number with a default of 1. The +libxx.so file usually is a symbolic link to the latest version. The +makefile for this project type is automatically created by the CDT. +* *Static Library* - A collection of object files that you can link into +another application (libxx.a). The CDT combines object files (i.e. *.o) +into an archive (*.a) that is directly linked into an executable. The +makefile for this project type is automatically created by the CDT. +* *Makefile Project* - Creates an empty project without the meta-data +files. This selection is useful for importing and modifying existing +makefile-based projects; a new makefile is not created for this project +type. ++ +By default, the CDT filters the *Toolchain* and *Project types* that +currently display in those lists based on the language support for the +{cpp} Project wizard you selected for this tutorial. ++ + +. From the *Project types* list, expand *Makefile project* and select +*Empty Project*. This project lets you enter the source file and the +makefile yourself. +. 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*. +. (Optional) On the *Select Configurations* page, Click *Advanced +Settings*. +* Expand *C/{cpp}Build > Settings*. Click the *Binary Parsers* tab. ++ +javascript:void(0)[Click here to see an illustration.] ++ +* In the *Binary Parser* list, select the error parser that is +appropriate for your platform. Other project settings can be modified +here as well. The default selection is probably OK. ++ +To ensure the accuracy of the C/{cpp} Projects view and the ability to +successfully run and debug your programs, selecting the correct parser +is important. After you select the correct parser for your development +environment and build your project, you can view the components of the +.o file in the C/{cpp} Projects view. You can also view the contents of +the .o file in the C/{cpp} editor. ++ +Click *OK* to close the Project Properties window. +. Click *Finish*. +. If a message box prompts you to change perspectives, click *Yes*. + +Your new project displays in the Project Explorer view. Your project is +empty because you have not yet created files for your project. You may +see an error since there is nothing to build yet for your project. You +can now start writing the code for your HelloWorld program. + +*Tip:* You can view and modify the properties of your HelloWorld project +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*] + +For more information about: + +* Projects, see *Workbench User Guide > Concepts > Workbench > +Resources* +* The workspace, see *Workbench User Guide > Tasks > Upgrading Eclipse* + +image:ngconcepts.gif[Related concepts,width=143,height=21] + +* xref:../concepts/cdt_c_over_cdt.adoc[CDT overview] +* xref:../concepts/cdt_c_projects.adoc[CDT projects] +* xref:../concepts/cdt_c_proj_file_views.adoc[Project file views] + +image:ngtasks.gif[Related tasks,width=143,height=21] + +* xref:../tasks/cdt_o_proj_files.adoc[Working with C/{cpp} project files] + +image:ngref.gif[Related reference,width=143,height=21] + +* xref:../reference/cdt_o_proj_prop_pages.adoc[C/{cpp} Projects view] diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_prepare_workbench.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_prepare_workbench.adoc new file mode 100644 index 00000000000..f6db147c8e4 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/cdt_w_prepare_workbench.adoc @@ -0,0 +1,66 @@ +//// +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 + +== Preparing the Workbench + +This tutorial will get you started using the C/{cpp} Development Toolkit (CDT) in the Workbench. + +First, you will verify that the workbench is properly configured for C/{cpp} development. It is assumed that: + +- Your Workbench has its default settings. To reset the current perspective to its original layout, from the menu bar select **Window > Reset Perspective**. + +- You are familiar with the basic Workbench features, such as views xref:../concepts/cdt_c_views.adoc[views] and xref:../concepts/cdt_c_perspectives.adoc[perspectives] + + +== Setting the global editor operations and appearance + +The main place to configure global editor-related preferences is the image:command_link.png[] xref:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)')[General > Editors] preference pages (also accessible through the **Window > Preferences** menu item) + + +== Setting the C/{cpp} editor operations and appearance + +C/{cpp}-specific editor preferences are under image:command_link.png[] xref:javascript:executeCommand('org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Editors)')[C/{cpp} > Editor]. +They include the following: + +- xref:../reference/cdt_u_c_editor_gen.adoc[Editor] - control the appearance of text highlighting +- xref:../reference/cdt_u_c_editor_con_assist.adoc[Content Assist] - customize the Content Assist feature +- xref:../reference/cdt_u_c_editor_folding.adoc[Folding] - customize folding behavior +- xref:../reference/cdt_u_c_editor_hov.adoc[Hovering] customize hover behavior +- xref:../reference/cdt_u_c_editor_mark_occurrences.adoc[Mark Occurrences] - set annotations +- xref:../reference/cdt_u_c_editor_save_actions.adoc[Save Actions] - configure actions performed while saving a file +- xref:../reference/cdt_u_c_editor_scalability.adoc[Scalability] - configure behavior for handling large source files +- xref:../reference/cdt_u_c_editor_color.adoc[Syntax Coloring] - specify how C/{cpp} source code is rendered +- xref:../reference/cdt_u_c_code_templates_pref.adoc[Templates] - configure the format of newly generated code stubs, comments and files +- xref:../reference/cdt_u_c_editor_typing.adoc[Typing] - configure formatting input as you type + + +image:ngref.gif["Related reference"] + +- xref:../reference/cdt_o_ceditor_pref.adoc[C/{cpp} Editor Preferences] \ No newline at end of file diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-footer.htm b/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-footer.htm new file mode 100644 index 00000000000..004b62dd2dc --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-footer.htm @@ -0,0 +1,2 @@ +
+

Copyright (c) 2000, 2025 Contributors to the Eclipse Foundation

diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-header.htm b/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-header.htm new file mode 100644 index 00000000000..97fef13afc5 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/docinfo-header.htm @@ -0,0 +1 @@ + diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/hw_example.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/hw_example.adoc new file mode 100644 index 00000000000..3e0f53da713 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/hw_example.adoc @@ -0,0 +1,48 @@ +//// +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 +Copy the code below and paste it into the *main.cpp* file in the Editor +view: + +.... +#include +#include +using namespace std; + +int main() +{ + string yourName; + + cout << "Type your name: "; + cin >> yourName; + cout << "Hello " + yourName << endl; + + return 0; +} +.... diff --git a/doc/org.eclipse.cdt.doc.user/src/getting_started/make_example.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/make_example.adoc new file mode 100644 index 00000000000..3fe1d83f410 --- /dev/null +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/make_example.adoc @@ -0,0 +1,44 @@ +//// +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 +Copy the script below and paste it into the *makefile* file in the +Editor view: + +.... +all: hello + +clean: + -rm main.o hello.exe hello + +hello: main.o + g++ -g -o hello main.o + +main.o: main.cpp + g++ -c -g main.cpp +.... diff --git a/doc/org.eclipse.cdt.doc.user/src/asciidoc/new_cmake_proj.adoc b/doc/org.eclipse.cdt.doc.user/src/getting_started/new_cmake_proj.adoc similarity index 64% rename from doc/org.eclipse.cdt.doc.user/src/asciidoc/new_cmake_proj.adoc rename to doc/org.eclipse.cdt.doc.user/src/getting_started/new_cmake_proj.adoc index c68b75c1863..6a302824fd4 100644 --- a/doc/org.eclipse.cdt.doc.user/src/asciidoc/new_cmake_proj.adoc +++ b/doc/org.eclipse.cdt.doc.user/src/getting_started/new_cmake_proj.adoc @@ -1,17 +1,16 @@ //// -Copyright (c) 2000-2024 QNX Software Systems and others +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 - -Contributors: - QNX Software Systems - original makefile project content - John Dallaway - initial CMake project content (#935) //// +// pull in shared headers, footers, etc +:docinfo: shared + // support image rendering and table of contents within GitHub ifdef::env-github[] :imagesdir: ../../images @@ -22,9 +21,16 @@ endif::[] // enable support for button, menu and keyboard macros :experimental: -= Creating a CMake project +// 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 -This tutorial describes the process of creating a new C/C++ project that includes a CMakeLists.txt file. +== Creating a CMake project + +This tutorial describes the process of creating a new C/{cpp} project that includes a CMakeLists.txt file. You need to create a project to contain your source code and related files. A project has an associated builder that can incrementally compile source files as they are changed. @@ -33,26 +39,26 @@ To create a project: . Select menu:File[New > Project]. -+ + When you create a new project, you are required to specify the project type. This project type will determine the toolchain, data, and tabs that the CDT uses/displays. -. Select the type of project to create. For this tutorial, expand the *C/{cpp}* folder and select *C/C++ Project*. +. Select the type of project to create. For this tutorial, expand the *C/{cpp}* folder and select *C/{cpp} Project*. . Click btn:[Next]. -+ -The *C/C++ Project* wizard opens: -+ +The *C/{cpp} Project* wizard opens: + + image:c_cpp_project_wizard.png[width=515] -+ -By default, the CDT presents all *C/C++ Project* templates. + +By default, the CDT presents all *C/{cpp} Project* templates. . Select the *CMake* template filter and choose from the following *CMake* project templates: -+ -- *CMake Project* - provides a simple C++ Hello World executable application project with main() and a supporting CMakeLists.txt file. + +- *CMake Project* - provides a simple {cpp} Hello World executable application project with main() and a supporting CMakeLists.txt file. - *Empty or Existing CMake Project* - provides an empty executable application project suitable for importing existing source and CMakeLists.txt files. . Click btn:[Next]. @@ -65,4 +71,4 @@ Your new project displays in the Project Explorer view. Your project may be empty because you have not yet created files for your project. You can now start writing the code for your application or importing code from elsewhere. -icon:arrow-circle-right[] link:pass:[../getting_started/cdt_w_newcpp.htm][Next: Creating your C++ file] +icon:arrow-circle-right[] xref:cdt_w_newcpp.adoc[Next: Creating your {cpp} file] 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..a56bb476be4 100644 --- a/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml +++ b/doc/org.eclipse.cdt.doc.user/topics_Getting_Started.xml @@ -4,7 +4,7 @@ - + diff --git a/pom.xml b/pom.xml index 1ff0637dc46..6855db01abe 100644 --- a/pom.xml +++ b/pom.xml @@ -1066,6 +1066,11 @@ build-helper-maven-plugin 3.6.0 + + org.asciidoctor + asciidoctor-maven-plugin + 3.1.1 + diff --git a/releng/scripts/do_all_code_cleanups.sh b/releng/scripts/do_all_code_cleanups.sh index 927890711ad..21241e7efda 100755 --- a/releng/scripts/do_all_code_cleanups.sh +++ b/releng/scripts/do_all_code_cleanups.sh @@ -21,3 +21,4 @@ ${DIR}/do_add_all_file_types_to_gitattributes.sh ${DIR}/do_project_settings.sh ${DIR}/do_rebuild_natives.sh ${DIR}/do_fix_file_permissions.sh +${DIR}/do_generate_asciidoc.sh diff --git a/releng/scripts/do_generate_asciidoc.sh b/releng/scripts/do_generate_asciidoc.sh new file mode 100755 index 00000000000..64518d60fb3 --- /dev/null +++ b/releng/scripts/do_generate_asciidoc.sh @@ -0,0 +1,39 @@ +#!/bin/bash +############################################################################### +# Copyright (c) 2025 Kichwa Coders Canada Inc +# +# 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 +############################################################################### + +set -e + +SCRIPT=$( basename "${BASH_SOURCE[0]}" ) + +## +# Make sure that asciidocs are up to date +## +for p in doc/org.eclipse.cdt.doc.user; do + echo "Rebuilding $p asciidocs to make sure they match source" + + echo "Ensure adoc files start with expected contents" + ref_header=$p/adoc-headers.txt + git ls-files -- $p/**/*.adoc | while read i ; do + end_line=$(awk '/\/\/ ENDOFHEADER/{ print NR + 1; exit }' $i) + tmpfile=$(mktemp /tmp/adoc.XXXXXX) + cat $ref_header > $tmpfile + tail --lines=+${end_line:=0} $i >> $tmpfile + mv -f $tmpfile $i + done + + echo "Generate html from adoc files" + logfile=asciidoc-${p//\//-}.log + if ! ${MVN:-mvn} -B -V generate-resources -DuseSimrelRepo -f $p >${logfile} 2>&1; then + echo "Rebuilding of $p asciidocs failed. The log (${logfile}) is part of the artifacts of the build" + exit 1 + fi +done