Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Getting started with CDT development
Contents
Eclipse installation
The very first thing you'll need to do to work on the CDT sources is install an Eclipse package. The Eclipse IDE for Eclipse Committers package contains the Eclipse platform plus other features that developers typically need to develop plug-ins, e.g., JDT, PDE and EGit (Eclipse Git Team Provider). Which version of Eclipse you need depends on which version of CDT you're building. To build the master branch of CDT today (June 27th, 2018), you need Eclipse 4.8 (Photon) or above. To build an earlier version of CDT, you might need to use an earlier version of Eclipse. Visit the CDT downloads page to see which version of Eclipse matches a particular CDT version.
Eclipse Setup
- Get the latest Eclipse IDE for Eclipse Committers (current Photon) from https://www.eclipse.org/downloads. You can also find older versions of the Eclipse (SDK) here: http://archive.eclipse.org/eclipse/downloads/
- Get the sources and import them into the workspace. See #Setting_up_the_Sources below for how to get the sources.
- Install API Tools Execution Environment Descriptions. You can install it by going to Help -> Install New Software..., then select the update site for the Eclipse Project matching your Eclipse version, currently it is http://download.eclipse.org/eclipse/updates/4.9
- Set up the dependencies, recommended way is by setting a Target Platform. See #Dependencies below for how to do that.
- Finally, after setting up the dependencies, set the API baseline in the Preferences. See CDT/policy#Using_API_Tooling
Setting up the Sources
For detailed information on how to setup git, and check out source of CDT as a committer, see CDT/git. Otherwise, follow the non-committer setup instructions below.
Clone the Repo
From the Git perspective, select Clone a Git Repository action
- Cut & Paste following url in the first page of wizard for cloning: https://git.eclipse.org/r/cdt/org.eclipse.cdt.git
- It will ask you what branches to import. If you only care about head select master, if you want to work with other branches select a corresponding branch, for example cdt_9_5.
- Press Next. As location where files are stored select a folder inside your workspaces, for example workspace/cdt-git
- Press Finish (skip Gerrit page)
- This should take about 3-5 minutes
From the repo, select Import Projects...
- Select all the projects or individual. It maybe easier select all, then close projects you don't need
Here's a list of projects you could start with:
- org.eclipse.cdt.codan.checkers
- org.eclipse.cdt.codan.checkers.ui
- org.eclipse.cdt.codan.core
- org.eclipse.cdt.codan.core.cxx
- org.eclipse.cdt.codan.ui
- org.eclipse.cdt.codan.ui.cfgview
- org.eclipse.cdt.codan.ui.cxx
- org.eclipse.cdt.core
- org.eclipse.cdt.core.native
- org.eclipse.cdt.core.linux (Platform specific, change accordingly)
- org.eclipse.cdt.core.linux.x86_64 (Platform specific, change accordingly)
- org.eclipse.cdt.core.macosx (Platform specific, change accordingly)
- org.eclipse.cdt.core.win32 (Platform specific, change accordingly)
- org.eclipse.cdt.core.win32.x86_64 (Platform specific, change accordingly)
- org.eclipse.cdt.debug.core
- org.eclipse.cdt.debug.ui
- org.eclipse.cdt.dsf
- org.eclipse.cdt.dsf.gdb
- org.eclipse.cdt.dsf.gdb.ui
- org.eclipse.cdt.dsf.ui
- org.eclipse.cdt.gdb
- org.eclipse.cdt.gdb.ui
- org.eclipse.cdt.launch
- org.eclipse.cdt.make.core
- org.eclipse.cdt.make.ui
- org.eclipse.cdt.managedbuilder.core
- org.eclipse.cdt.managedbuilder.gnu.ui
- org.eclipse.cdt.managedbuilder.ui
- org.eclipse.cdt.target
- org.eclipse.cdt.ui
If you want to run tests, add the corresponding test project, for example, org.eclipse.cdt.core.tests.
Dependencies
The easiest way to satisfy all dependencies for CDT is to set a target platform. The target platform will download all the dependencies so that you can compile and run your imported CDT plug-ins without having to install the dependencies in your Eclipse installation.
To set the target platform:
- Expand the "org.eclipse.cdt.target" project.
- Double-click on cdt.target.
- In the editor that just opened, click Set as Active Target Platform on the top right.
Eclipse will now download the required dependencies, which may take some time the first time. Once this is done, it should trigger a full build of your workspace and a lot of errors should go away.
If you wish to switch target platforms in the future, you can open a different .target file, or you can go to "Window -> Preferences -> Plug-in Development -> Target Platform".
Broken Dependencies
If you get lots of compile errors because Java is unable to find classes, especially those not related to CDT, the cdt.target might need updating. This is the case after an eclipse release and it can take a few days for the devs to update this file. You can verify that the problem is not at your end by having a look at the latest CI-Build.
Launching
After all the CDT projects have successfully built, you'll probably want to run and/or do source-level debugging of the CDT code. Open the PDE (Plug-in Development Environment) perspective: Window->Perspective->Other->"Plug in Development". There, you'll see a project with the name org.eclipse.cdt.ui, right click the org.eclipse.cdt.ui project, select "Run As"->"eclipse application". You should see a new instance of eclipse - with the latest version of eclipse CDT plugins.
Alternatively, you can create a Launcher: Go to Run - Debug Configurations... Select "Eclipse Application" and click New. Give the Debug Configuration a Name and the other defaults are OK. This appears to be a more widely used launching technique.
Until you are familiar with the CDT code base, using a Debug Launcher and experimenting with breakpoints is probably the best way to get a warm fuzzy feeling if you have doubts about modifications you are making.
Submitting and Applying Patches
If you wish to contribute your changes to CDT see these instructions.
Creating a runtime patch
If you want just patch up your local installation you can export plugin(s) to which source patch is applied:
- Right-click on the Project -> Export -> Deployable features -> Archive File.
- In your target installation: Help -> Install new software -> Add -> Archive -> Select the exported zip -> Add -> Make sure "Group items by category" is disabled -> Install as usual.
- You can verify the correct version is installed using Help -> About Eclipse -> Installation Details -> Plug-ins.
Building the CDT p2 repository
You can generate your own CDT zip using Maven.
- Install Maven if not already installed (mvn command). Maven 3.3 or greater is required.
- In command line, change the directory to the cdt git directory (the top folder that contains a pom.xml file)
- Run "mvn package". This will take a lot longer the first time because it needs to download a lot of things. If it seems stuck on a download and you're behind a proxy, make sure that you set your Maven proxy settings.
- If the build is succesful, the zip will be in org.eclipse.cdt/releng/org.eclipse.cdt.repo/target/org.eclipse.cdt.repo.zip
- Go to Install new software, click Add, Archive and browse for to the zip
You should now be able to install or update CDT using your modified code.
Using Oomph
(experimental If you get errors, please ask on the cdt-dev mailing list and someone can help get you up to speed.)
You can use the Eclipse installer (Oomph) to setup the Eclipse installation and everything required to get started with CDT development. It downloads Eclipse, sets the API baseline, clones the CDT git repo and imports the projects for you.
- Download the Eclipse installer, available at https://wiki.eclipse.org/Eclipse_Oomph_Installer
- Start the installer using the eclipse-inst executable (Eclipse Installer app on macOS).
- In the first page (product selection), click the preference button in the top-right corner and select the Advanced Mode button.
- If you are behind a proxy, at this point you might want to double check your network settings by clicking in the "Network Proxy Settings" at the bottom.
- Select Eclipse IDE for Eclipse Committers and select Latest as the product version. Click next. (Latest is 2020-12 as of Oct 2020. You normally need to use the version of Eclipse that you are targeting for development. As of Oct 2020 the CDT master is targeting 2020-12, although this changes with every release.)
- Under Eclipse Projects, select CDT. It should now be visible in the bottom list. Click next.
- Enter installation folder name, workspace name, etc. Click Next, Finish.
The initial setup can take a while. You should see some information in the status bar which you can click on (arrows) for details.
Some errors may occur after Eclipse launches and the Eclipse Updater starts. In this case, clicking <Back and Finish in the "Eclipse Updater" dialog a few times may be necessary. After the initial setup, you should have a complete Eclipse environment to work on CDT.
Merging of git repos
In January 2020 the git repos for numerous CDT and related code was merged into a single git repo. See Bug 558439. When working on master branch after January 2020 nothing special needs to be done. However if you are working with the launchbar or tools.templates components and need to build older versions you may want to clone the CDT repo multiple times and checkout the pre-merge commits, such as LAUNCHBAR_2_4_1 for the last release of the launchbar before the merge.
The old git repos will eventually be removed as their history has fully migrated to the main org.eclipse.cdt repo.