Configure Eclipse
Eclipse is an open source, multi-platform IDE (Integrated Development Environment) written in Java that provides a file browser, an editor, a SVN client, access to compilers and lot of other tools. It is neither part of SCDB, nor a requirement to use SCDB.
When used with SCDB, it brings a graphical interface for administering SCDB and editing templates. With very few customizations, Eclipse can be used to edit templates, compile them, and deploy machine profiles while taking advantage of all the advanced features you find in Eclipse: local history, file browsing and searching, ability to open a template directly at the line causing an error, and others.
Instructions in this page explain how to customize Eclipse for SCDB. This is not an introduction to Eclipse usage itself. Refer to online documentation in Eclipse. Configuration described here has already been tested on Linux, MacOS, and Windows but should work on any other platforms as all components used are pure Java.
Installation
Installing Eclipse
Eclipse can be downloaded from http://www.eclipse.org. The site provides pre-built distributions for Windows, Linux, and MacOSX making installation trivial. Recent versions of Eclipse offer several different pre-configured versions. For SCDB, the "Eclipse Classic" is the most appropriate.
Before being able to run Eclipse, you need to install Java JRE or JDK on your machine. SCDB requires Java 1.5 or later. You need to check on Eclipse site minimum Java version required by Eclipse. As of Eclipse 3.2, it was lower than SCDB.
If you have several Java JREs or JDKs installed on your machine, run Eclipse, goto Preferences->Java (in Window menu) and check the version used by Eclipse matches both Eclipse and SCDB requirements.
Note : Java JDK is required only for some advanced operations like generating new OS templates. Java JRE is enough for daily administration of SCDB.
Installing Easy Eclipse
As an alternative way to classic Eclipse installation evoked above, "Easy Eclipse" is a prepackaged release of Eclipse. There are several "flavours" of it, each one being dedicated for a specific type of development (you have the choice between : LAMP, Python, Ruby and Rails,....)
The main advantage of this release is that it is very simple to install. Just untar a file and you have a ready to use Eclipse, with the necessary plugins to access BEgrid SVN. I would also advice Easy Eclipse to 64 bit users, as it seems that the plugin "Colorer" to install with classical Eclipse doesn't seem to work in 64 bit environment, and it is no more maintained since a few years. With Easy Eclipse, you don't need this plugin anymore since it is shipped with a newer one, "Color Editor".
You can find Easy Eclipse here :
http://www.easyeclipse.org/site/distributions/index.html
You can choose the LAMP flavour. Download the tar.gz file and uncompress it ("tar xvzf ...") wherever you want.
Installation under a 64 bit Linux
If you are using a 64 bit operating system, then you'll also have to install the Sun Java JRE 32 bit (there is no 64 bit release), using the "self extracting file" rather than the RPM so as to avoid interfering with another existing 64 bit JVM. To force Easy Eclipse to use the 32 bit VM, you'll have to create a small launcher bash script. Here is an example of such a launcher :
export JAVA_HOME=/usr/java/32bits/jre1.6.0_17 cd /usr/share/easyeclipse-lamp-1.2.2.2/ ./eclipse $*
Just adapt and write this code to a file "eclipse.sh", make it runnable ("chmod ug+x eclipse.sh"). You'll also have to change the eclipse.ini file in the Eclipse installation directory to specify that you want to use the 32 bit VM :
-vm /usr/java/32bits/jre1.6.0_17/bin/java -vmargs -Xms128m -Xmx512m -XX:MaxPermSize=128m
(I've just added the first two lines in the default eclipse.ini.)
Note : you may meet some dependency problems launching the program for the first time. If it doesn't start normally, then have a look in the log file (usually ~/workspace/.metadata/.log). In my case, I had to yum-install the library libXtst.so.6.
Installating Eclipse plugins
Skip this section if you've installed Easy Eclipse.
For Eclipse to work with SCDB, some additional software, called plugins, needs to be installed. To do this, run Eclipse and use Software Updates->Find and Install...->Search for New Features to Install -> Next in Help menu. Then add a new remote site for each of the following plugins :
- Subclipse : used to interact with a SVN client. (To avoid dependency problems, deselect Mylar integration unless Mylar is installed in your version of Eclipse.)
- Download URL : http://subclipse.tigris.org/update_1.4.x
(Remark: There's no need for SVNKit anymore)
- Sunshade : used for error linking between console and editor (useful for opening templates where an error occurred)
- Download URL : http://sunshade.sourceforge.net/update
- Colorer (optional): used for syntax coloring in templates.
- Download URL : http://colorer.sf.net/eclipsecolorer/
After adding each site, select them and click on Finish button.
Configuration
File Encoding
You are encouraged to change the default encoding for the files that eclipse creates.
- To do so, go to Window -> Preferences -> General -> Workspace, and change the Text file encoding to something that's supported on the nodes managed by quattor (iso8859-1 ?).
- Also, you'll probably want to use UNIX newline styles, which you can choose in New text file line delimiter
JavaHL
Colorer
Easy Eclipse is already shipped with a syntax highlight plugin called "Color Editor". It must not be confused with the plugin "Colorer" of this section. So, if you've installed Easy Eclipse, you can skip this section, and jump to the section "Color Editor".
Colorer is used to do syntax coloring when editing PAN templates.
Syntax coloring rules are defined in a file pan.hrc that can be downloaded from Quattor CVS (in elfms/Quattor/utils/eclipse). This file must be placed in /path/to/eclipse/plugins/net.sf.colorer_VERSION/colorer/hrc/auto.
Then an entry for these syntax colouring rules must be added to /path/to/eclipse/plugins/net.sf.colorer_VERSION/colorer/catalog.xml. This is done by editing this file and adding the following line to the hrc-sets:
<location link="hrc/auto/pan.hrc"/>
Last, add an association between .tpl file extension and Colorer Editor. To do this, go to Window->Preferences->General->Editors->File Associations, add .tpl and associate the Colorer Editor with it.
For the new Colorer configuration to be taken into account, you need to restart Eclipse.
If you run into an error message like Error in initialization of native part of the Colorer library, this might mean 2 things
- colorer can't find the catalog.xml file
- this shouldn't happen by default setup
- some explanation where it looks for by default (http://colorer.sourceforge.net/api/classParserFactory.html)
- it can't load the libnet_sf_colorer library
- it can't find it
- this shouldn't happen by default setup
- the library is built against code that is not on your system
- linux
- locate the file (typically in $ECLIPSE_HOME/plugins/net.sf.colorer_x.y.z/os/linux/x86/
- run ldd $PATH_TO_DIR/libnet_sf_colorer.so
- see if you have everything
- eg on FC8, you need to install an additional rpm called compat-libstdc++-33
Color Editor
Color Editor is the default syntax highlight plugin embedded in Easy Eclipse. You will find more information about that plugin here : (http://gstaff.org/colorEditor/)
Here I will explain how to add the syntax highlight rules for the PAN language. Color Editor uses the same "mode" files as the famous JEdit editor. I created a very simple such mode file for PAN. You can download it here.
Now, you have to include this new mode file in the JAR archive of the Color Editor plugin. This *.jar includes a "modes" directory containing all the *.xml files describing the highlighting rules for the different languages known by Color Editor. First, you must copy the pan.xml file into a "modes" directory. Then, provided you are in the parent directory of "modes", you can type that kind of command :
jar uf /usr/share/easyeclipse-lamp-1.2.2.2/plugins/cbg.editor_1.2.6.jar modes/pan.xml
(Of course, you will have to adapt this command according to the directory where you've installed Easy Eclipse.) And finally, you will also have to change the modes/catalog file in the *.jar archive to add PAN to the list of known languages and to link the *.tpl file extension to PAN :
- Extract modes/catalog for plugin *.jar file :
cd /usr/share/easyeclipse-lamp-1.2.2.2/plugins/ jar xf cbg.editor_1.2.6.jar modes/catalog
- Modify the modes/catalog file, by adding the following section between the <MODES>...</MODES> tags :
<MODE NAME="pan" FILE="pan.xml"
FILE_NAME_GLOB="*.{tpl}" />
- Update the *.jar with the modified modes/catalog :
jar uf cbg.editor_1.2.6.jar modes/catalog
Note for the impatient user :
If you don't want to spend time doing all this, you can also simply download this modified plugin and copy it into the "plugins" directory of your Eclipse installation.
Sunshade
If you have Sunshade installed inside Eclipse, then you can hyperlink between errors generated by the pan compiler and the file. To do this you need to add some regular expressions to the Sunshade "Error Link" configuration. Open the Eclipse options panel (using Window->Preferences) and then navigate to the "Sunshade" and then "Error Link" pages. On this page add the following regular expressions:
\[panc\]\s*DEPRECATED:\s+(.*)\s+\[(\d+):(\d+)\] \[([^\[\]]+\.tpl)(?::(\d+)\.(\d+)-\d+\.\d+)\]
The links identified with these expressions will take you to the start of the expression causing the error. Note that the error messages give you the full range of the expression in the format "beginLine.beginChar-endLine.endChar".
Note : The regexp above are intended for panc v7 and later. If you are still using panc v6 or before, you need to use a different set of regular expressions. Both can coexist.
\[pan-syntax\]\s*(.*\.tpl):(\d+): \[pan-compile\]\s*(.*\.tpl):(\d+) \[pan-syntax\].*[\s\(](.*\.tpl)
JavaSVN and certificates
When using JavaSVN in combination with certificates, you must add the password in the ~/.subversion/servers file. Make sure that this file has correct access rights (as it contains cleartext password, it must have mode 400).
A full example looks like :
[groups] somegroup = some.full.host, *.some.domain [somegroup] ssl-client-cert-file = /bla/bla/bla.p12 ssl-client-cert-password=hahahahaha [global] ssl-authority-files = /bla/bla/bla/ca_local.crt
Configuring Java VM for Ant
Be sure to read instructions about running PAN compiler if you experiment any strange behaviour or slowness. It is recommended to run SCDB Ant tasks in the same Java VM as Eclipse workspace, especially if your machine doesn't have a lot of memory (1 GB or more). You can check the current setting by right-clicking on the build.xml file in ant pane and choosing Run As...->External Tools and then clicking on JRE tab.
Note: it is not possible to use the same Java VM as the workspace if you need to adjust some VM parameters like maximum memory.
Configure for the BEgrid trac
Setup steps to checkout the centralised repository:
- go to Window -> Show view -> Other -> SVN -> SVN Repository
- rightclick -> New -> Repository Location
- Url: https://quattorrepository.begrid.be/repos/centralised-begrid-v5/trunk
- Root: https://quattorrepository.begrid.be/repos/centralised-begrid-v5
- Press Finish (no login/passwd needed, only your certificate.)
- If there's an error, make sure that you are allowed to access the repository and that your .subversion/servers file is correctly set.
- rightclick on https://quattorrepository.begrid.be/repos/centralised-begrid-v5/trunk -> Checkout As -> Simple -> Project
- Give it a name: eg centralised-begrid-v5
- Finish
- In Navigator, there should be a folder called centralised-begrid-v5
- This folder contains a file .project. Rightclick -> Team -> add to: svn ignore
- With newer version of eclipse hidden files are not shown. So to be able to access them, Windows -> Navigation -> Show View Menu -> Filters
- Check the box called .* resources and press OK to confirm
- Create a new folder build (this one will contain all locally build xml-files, and these should never be uploaded). Rightclick -> Team -> add to: svn ignore
