Test major Koha Wiki changes or bug fixes here without fear of breaking the production wiki.
For the current Koha Wiki, visit https://wiki.koha-community.org .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.
[[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.