Build prerequisites | web-jekyll

# Build prerequisites

Tools required to build the plug-ins locally and run debug sessions.

## Install & Configure Eclipse

### Install Git for Windows

On Windows, the `git` command is available in the Git for Windows package.

It also comes with a minimal POSIX environment. To access it, start the `bash.exe` program.

### Install Sourcetree

For a convenient access to Git, it is recommended to install Sourcetree, available for macOS and Windows.

For GNU/Linux, either use GitKraken, or directly the command line Git.

### Install Java

Starting with Eclipse 2020-09, the minimum requirement is Java 11. The builds running on the Eclipse infrastructure currently use AdoptOpenJDK version 11 (LTS). For consistency reasons, it is recommended to install the same version.

Starting with 2020-09, Eclipse itself includes a JRE instance, and for normal use it no longer needs a separate Java. However, active development requires JDK; JRE is not enough, without JDK it is not possible to compile the plug-ins and run debug sessions.

Note: If you already have a more recent version of Java installed, or from a different distribution, you might be able to use it, but, for consistency reasons, it is still recommended to install AdoptOpenJDK 11.

Windows

Go to the AdoptOpenJDK download page:

- download the jdk-11* macOS .pkg file (surprisingly, the .tar.gz is not an usual archive; it includes the macOS package, and requires even more efforts to use)
- double click it to start the install; it’ll go into `/Library/Java/JavaVirtualMachines/adoptopenjdk-11.jdk`.

linux

### Prepare folders

- in a place of you choice (like `${HOME}/Work`), create a folder `eclipse-embed-cdt.github`
- inside it create a folder `develop`

    mkdir -p "${HOME}/Work/eclipse-embed-cdt.github/develop"

### Install Eclipse IDE for Eclipse Committers

This instance of Eclipse is specialised for Eclipse plug-ins development. The recommended version is 2020-09.

Windows

Go to the 2020-09 download page:

- identify the Eclipse IDE for Eclipse Committers section
- download the macOS binary (for example `eclipse-cpp-2020-09-R-macosx-cocoa-x86_64.dmg`)
- double click on the .dmg image file
- drag and drop the `Eclipse.app` into the `eclipse-embed-cdt.github/develop` folder
- remove the `com.apple.quarantine` attribute:

    xattr -cr Eclipse.app

- rename `Eclipse.app` to `Eclipse-committers-2020-09.app`

linux

### Start the new Eclipse

- in the `.../eclipse-embed-cdt.github/develop` folder create a new workspace named `eclipse-committers-2020-09-workspace` (note: be sure you create the workspace where you need it to be, since moving later is generally not supported by Eclipse; if you need this, preferably create a new workspace)
- check Use this as default…
- check if you installed the right Eclipse; go to the Eclipse menu → Help (Eclipse on macOS) → About Eclipse and the first line should read Eclipse IDE for Eclipse Committers

### Set Java 11 as default

- in the Eclipse menu → (Window →) Preferences → Java → Installed JREs
  - Add → Standard VM
    - JRE Home: select the `/Library/Java/JavaVirtualMachines/jdk1.8.0_221.jdk/Contents/Home` folder
    - JRE name: AdoptOpenJDK 11
  - click the Apply button
- in the Eclipse menu → (Window →) Preferences → Java → Installed JREs → Execution Environments
  - in the left pane select JavaSE-11
  - in the right pane select AdoptOpenJDK 11
  - click the Apply and Close button
- in the Eclipse menu → (Window →) Preferences → Java → Compiler
  - Compiler compliance level: select 11
  - click the Apply and Close button

### Install several Eclipse plug-ins

- Help → Install New Software
  - Work with: `2020-09 - https://download.eclipse.org/releases/2020-09`
    - In Application Development Framework
      - optional Eclipse Project SDK
    - In Mobile and Device Development
      - select C/C++ GCC Cross Compile Support
      - select C/C++ GDB Hardware Debugging
      - select C/C++ Memory View Enhancements
    - In Programming Languages
      - optional C/C++ Autotools
      - select C/C++ Development Tools
      - select C/C++ Development Tools SDK
      - optional C/C++ Docker Container Launch Support
      - optional C/C++ LLVM-Family
      - optional C/C++ Unit Testing Support
    - In Web, XML, Java and OSGi Enterprise Development
      - select Eclipse XML Editors and Tools
      - select Eclipse XSL Development Tools
      - select JavaScript Development Tools
    - click the Next button
    - accept the terms of the license agreement
    - click the Finish button
  - wait for the new plug-ins to be installed (in background, see status line)
- restart
- click the Workspace button in the top right corner

Note: Without the C/C++ Development Tools SDK which includes the CDT sources, the extension point schemas will not be available so attempts to add new elements to the extensions will not be possible, and only ‘Generic’ elements will be offered.

### Install baseline API

The API baseline checks that modifications made to the code maintain API compatibility with previous versions of Embedded CDT according to the rules and guidelines set out in Semantic Versioning Rules and Eclipse API Central.

- Ensure that `target-platform/org.eclipse.embedcdt.baseline.target` is a file in your workspace (in the `embed-cdt-plugins` project)
- in the Eclipse menu → (Window →) Preferences → Plug-in Development → API Baselines
  - click the Add Baseline… button
  - select A target platform
    - Enter name: `baseline` (The name is a convenience label only)
    - enable `embedcdt-baseline`
    - click the Refresh button
    - click the Finish button
- click Apply and Close

### Create and configure the workspace

- change the workspace preferences
  - go to the Eclipse menu → (Window →) Preferences…
  - General → Workspace
    - enable Refresh on access
    - set Text file encoding: UTF-8
    - click the Apply button
  - General → Editors → Text Editors
    - enable Show Print Margin (80)
    - enable Show Line Numbers
    - click the Apply button
  - General → Editors → File Associations
    - click Add and add `*.sh`, `*.command`, `*.ini`, `*.liquid`, `*.launch`
    - for each, click the Add button in the Associate editors area
    - associate with the Text Editor
    - click the Apply and Close button
  - go to the Eclipse menu → (Window →) Preferences…
  - Run/Debug → Console
    - disable Limit console output
    - click the Apply button
  - Java → Editor → Folding
    - disable Header Comments
    - disable Imports
    - click the Apply button
  - XML → XML Files → Editor
    - Line width 72
    - enable Split multiple attributes…
    - disable Align final bracket…
    - enable Preserve whitespace in tags with PCDATA content
    - enable Clear all blank lines
    - disable Format comments
    - enable Insert whitespace before closing…
    - enable Indent using tabs
    - click the Apply button
  - click the Apply and Close button

### Install a Eclipse CDT for tests

This separate instance of Eclipse will be used to test the plug-in.

Go to Eclipse download site and follow the download packages link.

#### Eclipse CDT 2020-09

From Eclipse download packages install Eclipse IDE for C/C++ Developers.

- download Eclipse IDE for C/C++ Developers (`eclipse-cpp-2020-09-R-macosx-cocoa-x86_64.dmg`)
- unpack the archive into the `develop` folder
- on macOS, remove the `com.apple.quarantine` attribute:

    xattr -cr Eclipse.app

- rename `Eclipse.app` to `Eclipse-cpp-2020-09.app`
- start Eclipse, use an workspace named `eclipse-cpp-2020-09-workspace`
- enable Use this as the default
- click the Hide button in the top right corner
- in the Eclipse menu → (Window →) Preferences → C/C++ → Appearance
  - disable Show source roots at top of project
  - click the Apply and Close
- in Project Explorer, click the three vertical dots icon → Filters and Customizations…
  - disable the .* resources line
  - click the OK button

Enable the Plug-in development perspective and switch to it.

## Clone the repositories

On Unix systems, the recommended method is using a command line:

    cd ${HOME}/Work/eclipse-embed-cdt.github
    git clone --recurse-submodules \
      https://github.com/eclipse-embed-cdt/eclipse-plugins.git \
      eclipse-plugins.git

On Windows, the `git` command is available in the Git for Windows package, it should have been installed from the first step.

## Import the projects

In the committers Eclipse, import projects using the generic importer:

- Eclipse menu → Project
  - enable Build Automatically
- Eclipse menu → File → Import
- Select
  - General → Existing Projects into Workspace
  - click Next
- Import Projects
  - Root Directory: `${Work}/eclipse-embed-cdt.github/eclipse-plugins.git`
  - enable Search for nested projects
  - disable Copy projects into workspace
  - disable Add project(s) to working set
  - click Finish

## Create the Maven run configurations

To start the plug-ins Maven build from Eclipse:

- in the `Embed CDT plugins root` set, select the `embed-cdt-plugins` project
- Eclipse menu → Run → Run Configurations…
- double click the Maven Build entry
- Name: `Embed CDT clean verify`
- in the Main tab
  - Base directory: click the Workspace… button and select the `embed-cdt-plugins`
  - Goals: `-V clean verify`
- click the Apply button
- in the JRE tab
  - select the Execution environment JavaSE-11 (to ensure compatibility with older environments)
- click the Apply button

Duplicate the configuration as `Embed CDT clean` and update the goal to `clean`.

## CDT Wiki

For more details, see CDT Wiki, especially the Getting started with CDT development page.