R3lib Development Environment Setup

Last update: May 15 2007

Currently R3lib is being developed under Windows XP, Eclipse and GNU Tools. All software needed for development except Windows is open-source. I am currently using this setup for development of 1.1.0 version of r3lib, that will contain Java API. This means that r3lib now contains two subprojects r3lib(c project) and r3lib4j(java project) and environment needs non-trivial setup for debugging of JNI calls.

Software

Other versions may work too, but the process was checked with these.

Java(TM) SE Development Kit 6 Update 1 (56,1 MB) (http://java.sun.com/javase/downloads/index.jsp)
Eclipse SDK 3.2.2, Windows (120,8 MB) (http://www.eclipse.org/downloads)
CDT 3.1.1 Runtime Feature (C/C++ Development Tools For Eclipse 11,6 MB) (http://download.eclipse.org/tools/cdt/releases/callisto/dist/3.1.1)
Cygwin (http://www.cygwin.com) Install GDB package, plus dependencies using setup.exe.
Subversion 1.4.3 for Win32 (5,0 MB) (http://subversion.tigris.org/project_packages.html)
Subclipse plug-in for Eclipse (15,1 MB) (http://subclipse.tigris.org/install.html) Install through Help -> Software Updates following directions from home page.
MinGW and MSYS (http://www.mingw.org/download.shtml), packages

Directory settings

These paths will be created in system. Some of them will be created by software installation, others need to be created manually.

<JRE_DIR> e.g. C:\Program Files\Java\jre1.6.0_01, directory with JRE installation
<JDK_DIR> e.g. C:\Program Files\Java\jdk1.6.0_01, directory with JDK installation
<WINSYS_DIR> e.g. C:\WINDOWS\system32, system directory
<CYGWIN_DIR> e.g. C:\cygwin, directory with cygwin installation
<MINGW_DIR> e.g. C:\mingw, directory with MinGW installation
<MSYS_DIR> e.g. C:\msys\1.0, directory with MSYS installation, shouldn't be the same as <MINGW_DIR>
<SVN_DIR> e.g. C:\svn, directory with subversion installation
<ECLIPSE_DIR> e.g. D:\eclipse, directory with eclipse installation
<WORKSPACE_DIR> e.g. D:\workspace, directory with working version of source code. We'll also set this as Workspace in Eclipse.
<SVNDB_DIR> e.g. D:\svndb, directory for subversion repository

We have to add following paths to PATH environment variable (using My Computer > Properties > Advanced > Environment variables)

<MINGW_DIR>\bin
<MSYS_DIR>\bin
<SVN_DIR>\bin

If PATH variable doesn't contain <WINSYS_DIR>, add it too. <CYGWIN_DIR> shouldn't be defined, so that MinGW and Cygwin don't get mixed.

Creating Subversion Repository

Copy r3lib.dump file into <SVNDB_DIR>
Enter directory <SVNDB_DIR>

Enter following commands

svnadmin create r3lib

      svnadmin load r3lib < r3lib.dump

This will create and load subversion repository diffengine.

Now we have to create windows service, so that other tools can access the repository

sc create svnserve binpath= "<SVN_DIR>\bin\svnserve.exe 
      --service --root <SVNDB_DIR>" displayname= "Subversion Repository" 
      depend= Tcpip

Then we start it and optionally we can set it to start automatically on Windows start-up

sc start svnserve sc config svnserve start= auto

Creating Eclipse Projects

In Eclipse, open perspective 'SVN Repository Exploring ' (Window > Open Perspective > Other... > SVN Repository Exploring) and add new repository location

svn://localhost/r3lib

Check-out trunk/r3lib as new project (Check out as a project configured using the New Project Wizard), name it 'r3lib', make it a 'Managed Make C Project' and choose Project Type 'Shared library (GNU on Windows)'

New directory '<WORKSPACE_DIR>\r3lib' will be created.

Create new subdirectory '<WORKSPACE_DIR>\r3lib\output' . It is used for debugging output.

Create file <WORKSPACE_DIR>\r3lib_postbuild.bat with following content:

cp <WORKSPACE_DIR>/r3lib/Debug/r3lib.dll 
      <WORKSPACE_DIR>/r3lib4j/lib

GCC settings

Configuration: Debug
Defined symbols: __int64="long long"
Include directories: <JDK_DIR>\include, <JDK_DIR>\include\win32 (location of jni.h and jni_md.h)
Linker flags: -Wl,--kill-at (as one flag, without space)
Post-build command: <WORKSPACE_DIR>\\r3lib_postbuild.bat (use \\ instead of \ in path)

Java project:

Check-out trunk/r3lib4j as new project (Check out as a project configured using the New Project Wizard), name it 'r3lib4j' and make it a 'Java Project'. Other settings can be left default.

Create folder <WORKSPACE_DIR>\r3lib4j\lib.

In Properties > Java Build Path > Source click on r3lib4j folder and set "Native library location" to workspace location r3lib4j/lib

Create file <WORKSPACE_DIR>\r3lib_javah.bat with following content:

cd <WORKSPACE_DIR>\r3lib4j

      javah -jni sk.linhard.r3lib.R3Tree

      move sk_linhard_r3lib_R3Tree.h <WORKSPACE_DIR>\r3lib

This will be used if a native method signature in the class R3Tree is changed and c headers have to be re-generated.

Eclipse Settings

Settings in Window > Preferences:

General > Workspace > Build automatically - leave unchecked (my personal preference)

Debugging JNI Calls

Let's say we have created Java Application Debugging Profile for project r3lib4j and we are in debugging perspective stopped on breakpoint just before call of native method. The Debug view should show name of system process that runs the java code. It should be <JRE_DIR>\bin\javaw.exe. Now we'll have to attach gdb debugger to this process.

Make sure that breakpoints are set in C code in the native method we are about to call.

Create new debugging configuration (Run > Debug...) of type 'C/C++ Attach to Local Application' for project r3lib.

Main tab: Choose <JRE_DIR>\bin\javaw.exe as 'C/C++ Application' on the Main configuration tab.

Debugger tab: Debugger: Cygwin gdb debugger, GDB debugger: <CYGWIN_DIR>\bin\gdb.exe

Source tab: Source > Add... > Path mapping. Then edit the mapping and add mapping 'Cygwin Path Translation' that properly translates your <WORKSPACE_DIR>\r3lib path from cygwin to normal representation. Now something about cygwin path representation. As part of debug information gcc includes paths to sourcefiles in final .dll, but it includes them in cygwin format. For example if we have directory 'E:\WORKSPACE\r3lib' cygwin format is '\cygdrive\e\WORKSPACE\r3lib'. That's why we need 'Cygwin Path Translation' mapping.

When debug configuration is done, press Debug button on Main tab and attach to the <JRE_DIR>\bin\javaw.exe process. There may be more such processes running in the system, you have to choose the right one. All threads in gdb debugger will be suspended. Make them running. This shouldn't do anything with the java debugger. Now return to java debugger (stopped just before native call) and press F8 (Resume). GDB debugger should now stop at defined breakpoint in native method.

This document serves mainly as notes for me, so that I don't forget how to configure my environment. There may be steps that I forgot to describe, but that wouldn't be fun if everything worked for the first time just by following some manual exactly step-by-step.

(c) Michal Linhard 2006-2007