Using Eclipse as IDE for Koha development

Eclipse is a popular IDE supporting various platforms and programming languages, including Perl (with the Epic plugin for Eclipse.). Debugging Koha scripts via Eclipse's CGI debugging is possible and fairly straightforward.

Suggested Koha development setup

A straightforward way to setup Koha for Eclipse development and debugging is via Linux LXC-containers. The official Ubuntu guides for LXC are a good source of information on how to setup and configure containers (https://help.ubuntu.com/lts/serverguide/lxc.html). This guide assumes Ubuntu 14.04 (Trusty) as the platform.

Koha installation

On Ubuntu, the lxc package can be installed by:

sudo apt-get install lxc

After installing the lxc package, create a 14.04 (Trusty) container:

sudo lxc-create -t download -n u1 -- -d kohadev -r trusty -a amd64

After the creation script finishes, you should have a new Ubuntu container 14.04 showing up via the lxc-ls-command:

sudo lxc-ls --fancy

NAME         STATE    IPV4        IPV6  AUTOSTART  
-------------------------------------------------
koha         STOPPED  -           -     NO         
kohadev      RUNNING  10.0.3.129  -     NO         
kohapreprod  STOPPED  -           -     NO

Consider putting the IP-address of the container into your /etc/hosts or into your ssh-config for convenience later. Consult the Ubuntu wiki for a full list of lxc commands.

The default user in the container is 'ubuntu' with the password 'ubuntu'. For future convenience, it is a good idea now to ensure that the user on the host-machine running Eclipse has proper access to the container filesystem in /var/lib/lxc/CONTAINER/... To do so, give add exec and read rights to the /var/lib/lxc folder, the container folder and to the rootfs-folder:

sudo chmod +rx /var/lib/lxc
sudo chmod +rx /var/lib/lxc/kohadev
sudo chmod +rx /var/lib/lxc/kohadev/rootfs

In addition, ensure that the uid of the koha-user in the container matches the uid of the user on the host machine. If the user on the host is the first created user, then it is convenient to use the 'ubuntu' user in the container for the koha installation.

To setup ssh-connectivity for the container, ensure that the container is running:

sudo lxc-start -n kohadev -d

And login with:

sudo lxc-console -n kohadev

login with the default credentials 'ubuntu' & 'ubuntu' (security is not a major concern here, considering this machine is only visible from the lxc-host, but you can change these). Install the openssh server:

sudo apt-get install openssh-server

Test that you can ssh into your container and proceed to perform a standard Koha (Git & Dev) installation in the container: Koha on ubuntu - git

Additional configuration for the container

Eclipse debugging will require remote database access to the mysql server running in the container. In order to allow database connections from the LXC-host machine to the container, create permissions in similiar vein to the ones you already created during your Koha installation:

GRANT ALL ON koha.* TO 'KOHAUSER'@'bridge-ip' IDENTIFIED BY 'KOHAPASSWORD';

Where the bridge-ip is the address of the Host-machine's bridge adapter (lxcbr0):

ip addr
...
4: lxcbr0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default 
    link/ether fe:65:11:21:ee:3f brd ff:ff:ff:ff:ff:ff
    inet 10.0.3.1/24 brd 10.0.3.255 scope global lxcbr0
       valid_lft forever preferred_lft forever
    inet6 fe80::e03c:33ff:fedb:4fba/64 scope link 
       valid_lft forever preferred_lft forever

Host configuration

Install the Koha perl dependencies:

echo deb http://debian.koha-community.org/koha unstable main | sudo tee /etc/apt/sources.list.d/koha.list
wget -O- http://debian.koha-community.org/koha/gpg.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install koha-perldeps

Create 2 additional folders for Eclipse under your kohaclone folder (fridolin.somers@biblibre.com):

mkdir -p /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/debug/opac/cgi-bin
mkdir -p /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/debug/admin/cgi-bin

And create 4 symlinks for Eclipse (fridolin.somers@biblibre.com):

ln -s /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/debug/admin/cgi-bin/koha
ln -s /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/opac /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/debug/opac/cgi-bin/koha
ln -s /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/api /var/lib/lxc/CONTAINER/rootfs/home/KOHAUSER/PATH-TO-KOHACLONE/debug/admin/api

Eclipse and Epic

Using the default version of Eclipse from the repos on 14.04 is not recommended (it crashes a lot). There are a number of ways you could install a newer Eclipse version - you could use the ubuntu-make (ex. developer tools center) or download Eclipse directly from the website: http://www.eclipse.org/downloads/packages/eclipse-ide-java-ee-developers/marsr.

To install a newer Eclipse version via ubuntu-make:

sudo add-apt-repository ppa:ubuntu-desktop/ubuntu-make
sudo apt-get update
sudo apt-get install ubuntu-make

umake ide eclipse

After you have a working Eclipse installation, install the Epic perl environment from http://www.epic-ide.org/download.php - follow the installation guide.

Install the Perl PadWalker-module from cpan:

cpan PadWalker

Koha-conf for Eclipse (fridolin@biblibre)

The host machine's Eclipse needs its own koha-conf.xml (koha-eclipse-conf.xml). The location of this file is not important like in the Koha container's installation. Use the attached example file to create your own by replacing the relevant parts with your paths.

CONTAINER = The name of the LXC-container where Koha is installed.
KOHAUSER = The username of the user that Koha is installed under in the container.
KOHACONF-FOLDER = The Koha configuration folder created in the container during Koha installation (default: koha-dev for dev installation).
PATH-TO-KOHACLONE = The path to the koha src-folder in the container.

[[1]]

When you have a proper koha-eclipse-conf.xml, proceed to create a Perl project in Eclipse.

Eclipse project definitions

Create a new Perl project from a custom location (unset the "use default location") and browse to your kohaclone folder in the container under /var/lib/lxc...

After setting up the project location, select 'Finish'.

Next, set up Perl include paths for the project (replace with your container name):

After setting up the include paths, it is a good idea to clean your project and do a full syntax check on the project (this might take some time). Select 'Project' -> 'Clean' from the upper Eclipse toolbar.

CGI debugging configuration

When your project has finished cleaning, you're ready to configure some CGI debugging environments. Right-click on your project and select 'debug configurations' under 'debug as'.

The first tab is self-explanatory - second tab is important. The second tab is important:

HTML Root Directory = koha-tmpl-directory under your container's kohaclone folder.
HTML Startup file = the index.html file under the koha-tmpl-folder.
CGI Root Directory = This points to the folder created earlier. /debug/admin or /debug/opac depending on whether you're debugging opac or staff.

In the environment-tab, setup 3 variables:

KOHA_CONF = this is the place for your koha-eclipse-config.xml created earlier
KOHA_PATH = full path to kohaclone in the container.
PERL5LIB = same as above.
MOJO_MODE = production in order to enable REST API calls

REST API calls can be debugged with this configuration for intranet by calling literally this location:

http://localhost:PORT_FOR_DEBUGGING/api/v1/app.pl/api/v1/patrons

This is an example for calling patrons API. The ugly URL is here due to unavailability of the Apache's RewriteEngine within an EPIC debugger.

You'll need separate configurations to debug staff-client and the opac-client. The only difference will be in the 'Web Server' tab where the path will be /debug/opac instead of /debug/admin.

Your configurations should now be ready for CGI debugging sessions.

Caveats and problems

As mentioned in the Epic guides, the debugging features won't work with scripts missing the .pl suffixes. A possible workaround is to temporarily modify the files with the suffixes - breakpoints seem to still break regardless of the setup with scripts missing suffixes.

Eclipse

Contents