.. _Eclipse intro: Eclipse introduction and installation ===================================== Software development on clusters -------------------------------- `Eclipse`_ is an extensible IDE for program development. The basic IDE is written in Java for the development of Java programs, but can be extended through plugins. The IDE was originally developed by IBM, but open-sourced and has become very popular. There are some interesting history tidbits on `the WikiPedia entry for Eclipse `_. *Eclipse is best run on your local computer, using its features to transfer code to a cluster for easy testing on the cluster. We do give some hints on how to use Eclipse. However, as it is a toolkit where almost everything is optional, and since the way it works also depends a lot on your local configuration, we cannot fully support it.* Some attractive features ```````````````````````` - Multi-platform: Available for Windows, macOS and Linux, and works mostly the same on all these platforms. - Support for C/C++ (via de CDT plugin) and Fortran (via the PTP plugin) development. This goes far beyond syntax coloring and includes things like code refactoring, build process management, etc. - Support for the development of parallel applications on a cluster, including automatic synchronisation of the source files on your laptop or desktop with one or more cluster accounts. So you can easily do code development while off-line and test on multiple clusters. Eclipse is heavily promoted (and actively developed) within the XSEDE collaboration of supercomputer centres in the USA. If you have suitable compilers and libraries on your local machine, you may even be able to do part of the testing and debugging on your local machine, avoiding delays caused by the job queueing system. Another advantage of running Eclipse locally rather than on the cluster is that the GUI has all of the responsiveness of a local program, not influenced by network delays. - It integrates with most popular version control system (offering a GUI to them also). Caveats ``````` Key format '''''''''' Not all of Eclipse supports the newer formats for OpenSSH keys or newer key types. As of the 2019-06 version, the EGit component that can be used to interact with Git servers such as GitHub, defaults to a new ssh implementation that supports all key types in use at the VSC in several OpenSSH-compatible formats. However, the other components that use ssh still use an older ssh implementation. That one does support RSA 4096-bit keys but does not yet support ed25519 keys. Moreover, it does not support the new (proprietary but open source) format used for private keys by OpenSSH but only the older (and more standard) OpenSSH PEM-format. You can recognize such keys if you open the private key file in a text editor. Suitable keys will start with ``-----BEGIN RSA PRIVATE KEY-----``. Keys converted by PuTTY from the PuTTY format are suitable for Eclipse. However, keys generated by recent versions of the OpenSSH ssh-keygen command on macOS or Linux (including the various Linux-compatible options for Windows) are not compatible with some Eclipse functions. If your key has the wrong format, you'll either need to generate a new OpenSSH RSA key for use with Eclipse by adding the ``-m PEM`` option to ``ssh-keygen`` (and otherwise proceed with the regular instructions to add another key to your account) or convert your private key (assuming it is a RSA key) to the PEM format. One easy way to convert your key to PEM format is by using ``ssh-keygen`` with the ``-p`` option to change the passphrase. Assuming your private key is called ``id_rsa_vsc``: :: $ cd ~/.ssh $ ssh-keygen -e -p -m PEM -f id_rsa_vsc >id_rsa_vsc_PEM Remote parallel debugger '''''''''''''''''''''''' The documentation of the Parallel Tools Platform also tells you how to launch and debug programs on the cluster from the Eclipse IDE. However, this is for very specific cluster configurations and we cannot support this on our clusters at the moment. You can use features such as syncrhonised projects (where Eclipse puts a copy of the project files from your desktop on the cluster, and even synchronises back if you change them on the cluster) or opening a SSH shell from the IDE to directly enter commands on the cluster. Release policy `````````````` The eclipse project works with a \\"synchronised release policy\". Major new versions of the IDE and a wide range of packages (including the C/C++ development package (CDT), Parallel Tools Platform (PTP) and the Fortran development package (Photran) which is now integrated in the PTP) occur simultaneously. This used to be once a year. However, in September 2018 Eclipse switched to a 3-monthly release schedule. Since that release, Eclipse no longer uses names for the release, but simply denotes them as 2018-09 and so on, based on the year and month of release. Under the hood a different version numbering system is still used though for the platform part (currently the 4-series, 2019-06 uses platform version 4.12), and plugins all have their own version numbering. Getting eclipse --------------- The best place to get Eclipse is the the official `Eclipse packages download page`_. That site contains various pre-packaged versions with a number of extension packages already installed. The most interesting one for C/C++ or Fortran development on clusters is \\"Eclipse IDE for Scientific Computing\". The installation instructions depend on the machine you're installing on, but typically it is not more than unpacking some archive in the right location. You'll need a sufficiently recent Java IDE on your machine though. Instructions are available on the `Eclipse Wiki `_. The CDT and PTP plugins integrate with compilers and libraries on your system. For Linux, it uses the gcc compiler on your system. On macOS it integrates with gcc (which you may need to install using either `Homebrew `_ or `MacPorts `_ and on Windows, you need to install `Cygwin`_ and its GCC toolchain. The Eclipse documentation is also available on-line on the `Eclipse`_ website. - Check out some :ref:`macOS specific issues here `. Basic concepts -------------- - A workspace is a place where Eclipse stores a set of projects. It corresponds to a folder on the file system. The actual files of project can but do not need to be in that folder. However, all internal data that eclipse maintains will be. A user can have more than one workspace. Eclipse will ask at the start which workspace to use for the current session. Workspaces are not easily portable between computers. They are simply a way to organise your projects on your local computer. - Each workspace can contain one or more projects. Each project is a collection of resources, e.g., C files or Fortran files, and typically has a releasable component that can be build from those resources, e.g., an executable. It is a good idea to use workspaces to group a number of related projects. A project also corresponds to a folder in the file system. That folder does not have to be contained in the workspace folder. Projects can be transported easily from one workstation to another. - A perspective defines the (initial) layout of views and editors for a particular task. E.g., the C/C++ perspective shows an editor to edit C/C++-files and views to quickly navigate in the code, check definitions, etc. The Debug perspective is used to debug an application. The PTP also has a system monitoring perspective to monitor jobs. Interesting bits in the documentation ------------------------------------- - The `Eclipse documentation `_ with a `getting started section `_ (Link changes with every update unfortunately) - Parallel Tools Platform: - `Parallel Development User Guide - Introduction to PTP Project Types - Synchronized `_ explains the advantages and disadvantages of the "Synchronized project type". - The PTP also supports modules to configure the remote shell before actually building the application: `Parallel Development User Guide - Configuring Environment Modules `_. - `The PTP Wiki `_