Eclipse

= 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.
[] 
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.
Category:Development