Eclipse - How to Setup Eclipse in a Shrew Checkout

From OPeNDAP Documentation
⧼opendap2-jumptonavigation⧽

Eclipse as an IDE for Shew

It can be useful to use an IDE when debugging and developing for Hyrax due to the graphical interface to gdb as well as the extensive searching and code indexing features that Eclipse provides. This document will go through the steps for getting Eclipse set up pointing into a Shrew checkout. We also explain how we set up debug configurations for debugging modules using the besstandalone program.

Downloading Eclipse

Eclipse may be found at http://eclipse.org/downloads/

Download the Eclipse for C/C++ Development (with Mylyn Integration).

If you also plan to do Java development, you can add these bundles in later using the Software Update.

Creating a Workspace In A Shrew Directory

You need to have a shrew project checked out and built in debug mode using the standard approach. The first-time debug build is required after a fresh checkout in order to get autoconf and configure to run properly and set up the Makefile for all the projects. Eclipse will then piggyback on these.

If you do not have this done already, please follow the steps in the next section "Setting Up a Debug Shrew Project"

Setting Up a Debug Shrew Project

Go to the directory you want the shrew project and do a checkout. For example, to get the fully trunk shrew:

svn co http://scm.opendap.org/svn/trunk/shrew

Note that shrew uses svn externals, so make sure you know which versions you are getting so when you commit you are commiting to the right place!

To check the externals being used, get the property in the shrew directory you checked out:

svn propget svn:externals

which for the trunk shrew returns: 

aries@chinchilla$ svn propget svn:externals
^/trunk/libdap src/libdap
^/trunk/bes src/bes
^/trunk/dap-server src/modules/dap-server
^/trunk/freeform_handler src/modules/freeform_handler
^/trunk/fileout_netcdf src/modules/fileout_netcdf
^/trunk/netcdf_handler src/modules/netcdf_handler
^/trunk/hdf4_handler src/modules/hdf4_handler
^/trunk/hdf5_handler src/modules/hdf5_handler
^/trunk/ncml_module src/modules/ncml_module
^/trunk/wcs_gateway_module src/modules/wcs_gateway_module
^/trunk/wcs_module src/modules/wcs_module
^/trunk/olfs src/olfs


Module Development/Debugging

If you plan to debug or develop modules for the BES in Hyrax 1.6, we suggest you use:

http://scm.opendap.org/svn/branch/shrew/module_dev_1.6

as the shrew starting point as this will be set to use the trunk versions of the modules but to use the fixed, release versions of libdap and the BES for Hyrax 1.6. This ensures that development doesn't use any new APIs from the libdap or bes trunk versions so that modules may be released incrementally and dynamically work with an existing Hyrax 1.6 installation with no other changes necessary.

Configuring a Debug Build

Since you likely plan to use the shrew project for debugging in Eclipse, you'll want to run the build_hyrax_debug script in order to make sure the configuration for all the subprojects is set up to perform debug builds (i.e. no optimization and full symbol tables). That way Eclipse will be able to find breakpoints and let you view variables in a running debug.

In a bash terminal in the top-level shrew directory, type:

source build_hyrax_debug

This will run autoconf on everything, then configure, then build it. If there are any missing dependencies, make sure to get them until everything builds. This will ensure that all the subprojects are configured properly so that the Eclipse Build command, which simply calls 'make', will succeed in compiling a debug version of the specified project.


Pointing the Workspace at Shrew Using Existing Makefiles

New Workspace

First, create a new workspace if you have an existing one. You can use:

File > Switch Workspace > Other...

and just create a new directory for the workspace to make the new one.


New Project for BES and/or Libdap

If you plan to modify the BES or libdap, you can make a project for each of these as well in the same way, but by pointing the location of the project at the appropriate subdirectory (src/bes or src/libdap) of the top-level shrew checkout.

New Project for a Module

In this section, we'll set up the subproject for a particular module you'll want to develop or debug. I will use the ncml_module as the example since this is the one I normally develop and I have added some tools to the project to make setting up debugging files easier.

Create the project just like the shrew project, using an Empty Project in the Makefile Project tab. Set the location to be the subdirectory of the top-level shrew, e.g.

src/modules/ncml_module

This will create a separate project tab for the module. If you click on this project and press the Build button (with the hammer icon), just that project will be built.

Set the Include Path

Setting the include path in the workspace will avoid the "can't find include" problems in the IDE. The Makefile may have the includes, but Eclipse doesn't know where to find them.

Under the Project -> Properties dialog (making sure to have the module project selected):

  • Click the "C/C++ General" tree to open it.
  • Select "Paths and Symbols"
  • On the "Includes" tab, add libdap and bes to C++ language include paths:
    • Click "Add..."
    • Select all checkmarks: "Add to all configurations", "Add to all languages" and "Is a workspace path".
    • Hit the "Workspace..." button and browse to the "shrew/src/libdap" and add it. It should show up as "/shrew/src/libdap" since we selected "is a workspace path"
    • Do the same for the bes include dir.

Debugging a Module

In order to debug a given module, we need to set up a Debug configuration for it. The way I do this for the ncml_module is by using the besstandalone application and pointing it at the same generated bes.conf file that the Autotest testsuite uses (all the modules should have this structure at this point). This makes sure the required modules get loaded, and in particular, the testsuite bes.conf points at the locally compiled module shared object in the project .libs directory, so 'make install' isn't required. We will also need a BES XML command file to automatically run the command we want to debug. For the ncml_module, this means we load a given NcML file and ask it for a particular response type (DAS, DDS, DDX, DODS) and perhaps with a constraint. Then we need to make sure Eclipse knows where to find the dynamically loaded library. Let's go through these steps one by one.

Create a New Debug Configuration

Go to:

Run > Debug Configurations...

When the dialog pops up, select the "C/C++ Application" entry and "New" to create a new configuration. This should pop up the configuration options for the new Debug Configuration.

We'll want to make changes in several of the tabs.

Main Tab: Select besstandalone as the application to run

Now we want to set these options to run besstandalone with the arguments we want. To do this:

  • Select the "Browse..." button under C/C++ Application.
  • Go up from the module directory to the shrew directory and into its "bin" directory (this should exist if you did a successful build_hyrax_debug).
  • Select the executable besstandalone

The application path will then loom something like this:

/Users/aries/src/module_dev_1.6/bin/besstandalone

Leave "Connect process input & output to a terminal" checked. We want to see the output in the Console.

Leave the configuration window open for the next changes.

Arguments Tab

Now select the "Arguments" tab.

Under the Program Arguments text field, enter the arguments to give to besstandalone as follows. First, make sure the working directory is the module directory, i.e.

${workspace_loc:ncml_module}

in our case.

Our testsuite directory in ncml_module is "tests", so that's where our bes.conf lives. Note that other modules use the directory bes-testsuite instead.

Here's the arguments list we will use for the ncml_module:

-c tests/bes.conf -d"cerr,ncml,ncml:2" -i tests/eclipse_debug.bescmd

Here we:

  • Specify the bes.conf to use in the testsuite directory so that we load the locally compiled (uninstalled) module
  • Turn on a few debug channels, here: "cerr", "ncml" and "ncml:2" which the ncml_module uses for debug output.
  • Tell besstandalone to use the file "tests/eclipse_debug.bescmd" as its input file.

Note that the "eclipse_debug.bescmd" file doesn't yet exist. This is a file that we recreate for each test we want to do. It can be made by hand, but the ncml_module has a script in tests called "generate_bescmd" that creates a BES XML command for a given ncml file and response type.

Here's an example eclipse_debug.bescmd for the DAS response for "/data/ncml/fnoc1_improved.ncml": 

<?xml version="1.0" encoding="UTF-8"?>
<request reqID="some_unique_value" >
    <setContext name="dap_format">dap2</setContext>
    <setContainer name="c" space="catalog">/data/ncml/fnoc1_improved.ncml</setContainer>
    <define name="d">
        <container name="c"></container>
    </define>
    <get type="das" definition="d" />
</request>

If you're using some other module, you probably want to copy this into a new file eclipse_debug.bescmd and modify it as your debug needs change, such as to test different responses.

Debugger Tab

Next, select the Debugger tab.

  • Decide whether to leave "Stop on startup at: main" selected or not. I usually leave it selected for the first pass just to be sure I can get a breakpoint in the besstandalone main() function in case there was a problem. You can edit the configuration to deselect it later.
  • Under "Debugger Options", select the "Shared Libraries" tab.
  • Make sure "Load shared library symbols automatically" is selected since our modules are dynamically loaded.
  • Under Directories, click the "Add..." button
  • "Browse..." your way to select the .libs directory in the module directory. In our case the full path ends up being: /Users/aries/src/module_dev_1.6/src/modules/ncml_module/.libs. This should match the module loaded in the bes.conf!
  • Leave "Stop on shared library events" unchecked since this will break on every library that gets loaded otherwise.

Apply Changes

On the bottom of the configuration, click "Apply" to save the changes.


Test It

If you're still in the debug configuration window, you can click the Debug button (assuming you have created a valid eclipse_debug.bescmd file) to run the debugger. If all worked out and you left Stop on startup at main selected, you will eventually get a breakpoint in the bes StandAloneApp.cc main() function!

From now on, if you have the module selected in the project window, you can click the Debug button (the bug icon) (or use Run > Debug).

You might also want to go to the top-level module initialize call and set a breakpoint to make sure you're module gets loaded properly and that you can stop on a breakpoint in it. For the NcML Module, this is the file:

NCMLModule.cc

and the function

NCMLModule::initialize( const string &modname )

Retrieved from "https://docs.opendap.org/index.php?title=Eclipse_-_How_to_Setup_Eclipse_in_a_Shrew_Checkout&oldid=5647"