xorg/ Development/ Documentation/ UsingEclipse

Using Eclipse CDT to develop Xorg

  1. Benefits
  2. Screenshots
  3. Installation How-to
  4. Introduction
  5. Xorg How-to
  6. Code Formatting
  7. Full tree setup
  8. Tips
  9. Other plugins

Benefits

  • Code Navigation
    • CDT 4.0 includes a fast code indexer and navigator which allows you browse call hierarchy, and quickly jump to the symbol declarations.
  • Debugging
    • acts as an interactive frontend to the GDB debugger
    • allows remote debugging via gdbserver
  • It doesn't get in the way
    • it doesn't require any particular directory layout
    • it doesn't require any particular build system, i.e., it plays nicely with autotools, hand-written Makefiles, or any build system which can output a build log
    • it has a configurable C coding style
    • it provides access to the GDB console while debugging
    • it has powerful regular expressions searching and replacing abilities

Screenshots

[[!img Error: bad image filename]]

[[!img Error: bad image filename]]

Installation How-to

If you're only interested in C/C++ development the simplest option is to download Eclipse IDE for C/C++ Developers and extract it into /opt.

Otherwise, you can always install CDT from the Eclipse Update Manager.

Then install the Eclipse-Autotools integration plugin, which provides assistance for projects using autotools.

Introduction

Eclipse organizes code in projects and workspaces.

  • A project is equivalent to a X.Org module. Projects have different build settings and separate source repositories.
  • A workspace is a set of related projects. Workspaces have different settings, and a workspace can only be opened by a single instance of Eclipse at any given time.

NOTE: You don't need to create a project for every single X.Org module, and that would be overkill. The modules you are planning to actively develop and debug are perfectly sufficient, as you can still open and debug through files outside the projects.

Eclipse organizes windows in views and perspectives.

  • A view is a display. You can add and re-arrange existing views.
  • A perpective is a set of views in a given layout. You can switch perspectives. The most interesting are the C/C++ and the Debug perspective.

Xorg How-to

It is assumed you have installed the xorg development packages from your distribution, or you have built xorg from source as explained in the Building the X Window System in /opt/xorg.

  • Initial configuration
    • Start eclipse and enter the path to your workspace (it can be an inexistent directory as Eclipse creates one for you)
    • You'll be presented with the welcome screen. Click to go to the workbench.
    • Switch to the C/C++ Perspective by going to Window > Open Perspective > Other... > C / C++
    • In Window > Preferences > C/C++ > Environment dialog set the following environment variables 
      LD_LIBRARY_PATH=/opt/xorg/lib
ACLOCAL="aclocal -I /opt/xorg/share/aclocal"
CPPFLAGS="-I /opt/xorg/include"
CFLAGS="-O0 -g3 -fmessage-length=0"
CXXFLAGS="-O0 -g3 -fmessage-length=0"
  • Create a project for xserver
    • In a terminal do: 
      cd /path/to/your/workspace
git clone https://gitlab.freedesktop.org/xorg/xserver.git
    • File > New > GNU C Autotools Project * Set xserver as the project (the same as the git module)
    • In Project > Properties dialog, C/C++ Build > Settings > Tool Settings tab * Under configure > General > Directory specifiers set the installation directory (--prefix) to /opt/xorg * Under configure > Features and packages set Enable maintainer mode (--enable-maintainer-mode) and enter any other configuration options you wish to pass to configure
    • Press Ctrl+B to build the project.
    • To switch between configure output and the make output go to the Console view, and click on the Display Selected Console button.
    • Double-click install target of the Make Targets view.
  • Debug Xnest locally
    • In the Debug > Debug settings... dialog, under C/C++ Local Application click on the New button
    • Set /opt/xorg/bin/Xnest as the application path
    • Set as arguments :1
    • Click on the Debug button.
    • The gdb console is available from the Console view, Console by clicking on the Display Selected Console button.
  • Debug Xorg remotely
    • rsync the /opt/xorg directory to the remote machine 
      rsync -av --delete /opt/xorg/ your-remote-machine:/opt/xorg/
    • in the remote machine run 
      gdbserver :10000 /opt/xorg/bin/Xorg
    • In the Debug > Debug settings... dialog, under C/C++ Local Application click on the New button
    • Set /opt/xorg/bin/Xorg as the application path
    • Choose gdbserver in the Debugger tab
    • Enter the hostname and of the remote machine and the port that gdb is listening to
    • Click on the Debug button. You can add more modules and/or debug targets in a similar fashion.

Code Formatting

CDT allows to specify the C code style from Window > Preferences > C/C++ > Code style property page.

You can import this profile, which was made to follow these (un)official guidelines as close as possible.

There is also a code style for Mesa.

Full tree setup

You can add the whole tree as a project, which is advantageous when cross-module work is done, or you are interested in module interdependecies. However, index generation can get darn slow then. Manually specifying include directories and disabling automated discovery in the project's discovery options may be helpful.

Also, eclipse prior to ganymede had the tendency to spend a few minutes on collecting the (admittedly huge) index whenever you'd type a member access operator (. or ->). Disabling Content Assist should help that.

Tips

  • To avoid out-of-memory errors change the last lines of eclipse.ini to 
    -vmargs
-Xms64m
-Xmx1024m
  • The autotools plugin simplifies the invocation of autoconf and automake, but it has some bugs that you should watch out for:
  • In Window > Preferences > General > Keys bind Ctrl+B to build the current project, instead of all projects.
  • In Window > Preferences > General set to Always run in background
  • In Window > Preferences > Run/Debug > Launching set to Launch the previous launched application

Check more tips in:

Other plugins

Must have:

Optional:

  • Target Management plugin -- simplifies remote debugging and testing by allowing to seemingly manipulate remote files and shells.
  • egit -- git integration plugin -- is still on early stages of development with very limited functionality and must be compiled from source, but it already provides a visual history viewer similar to gitk.