Eclipse IDE is an integrated development environment that can be used to develop programs in a variety of programming languages, including Java and C/C++. For a good summary, check Wikipedia’s Eclipse (software) webpage.
It is my preferred IDE, but, unfortunately, while Eclipse has a lot of documentation, the documentation often does not provide enough details, and may be difficult to read and understand. As my clients often needed help with Eclipse deployment, they asked me to write few technical guides regarding it and Eclipse usage in general.
Today I am posting a draft version of the first book that tentatively called Installing Eclipse on Windows for Java and C/C++ Developers (HTML, PDF format is also available). To use the book interactive features, the reader will need a modern desktop browser (mobile and IE browsers will not work).
While the book is quite useful in its current state, it requires some polishing. So please pardon my grammar – English is not my native language.
It is the first book in Eclipse series, the other books that are coming will be about using Eclipse with Git and installing Eclipse for Python and JavaScript developers. While substantial parts of the books are dedicated to handling Eclipse on Windows, there are also parts that may be interesting to people using other platforms.
The book is written as a detailed walk-through that is illustrated with tons of screenshots. It describes how to install Eclipse IDE itself, Java SE, and Cygwin (of interest to C/C++ developers). If readers go through the pages and perform steps in the prescribed sequence, they will have Eclipse ready in no time (just kidding 🙂 ).
This work is sponsored by AIMK Consulting Incorporated company that allowed me to use its resources while writing the books.
The Audience
One of the challenges was to make the book useful to a wide audience. Potential readers can be installing Eclipse for themselves or their friends (such as students or developers) or for large group of people (such as administrators or other power users). The reader experience can also vary.
It is assumed, that the reader can use Microsoft Windows, browse websites and download files from the Internet. In the case of administrators and power users wanting to have shared Eclipse installation, it is also expected that they know how to take care of permissions and work with network folders (if needed).
Casual users of Windows can find some help in the book appendixes (such as creating desktop shortcuts). On another hand, experienced readers may also find the appendixes useful (such as managing Eclipse software).
The book is written in such a way that its main text contains all required information except few cases. Specifically, the reader in general shall look in the appendixes if they need help, there are problems, or if they want to use Eclipse installer in advanced mode (that is intended mostly for admin/power users).
The Scope
Some people still run Windows XP, some people still use 32bit software, some people still need Java 8. Initial version of the main text contained information about legacy Windows and other legacy software. As it was rather difficult to read, all such information has been moved to appendixes.
While the main text describes 64bit Eclipse and Java 11 installation on Windows 10, the appendixes detail 32bit, Java 8, and Java 10 cases.
Moving Target
Technology today is changing so fast that technical guides can become obsolete while still in process of writing. While I was making this book, few events happened that forced me to redo it.
Oracle has released Java 11, changed licensing, and dropped Windows installer. So the main text describes now how to install Oracle OpenJDK for Java SE 11 (while there are appendixes about other Java variants).
As Java application launching was also dropped, the book now explains how to specify Java runtime required by Eclipse launcher.
Eclipse installer became mature enough. So the main text depicts the installer usage in simple mode (while there are appendixes about its advanced mode and about installing from zip archives).
Eclipse changed release model. When previously it had named releases like “Photon”, now it has few numbered releases per year like “2018-12”. Nothing much to worry about, except that example pathnames and screenshots had to be replaced.
Did I mention screenshots? It seems that application developers take pleasure in changing their application looks in every release. Thank you very much, I so enjoy making new screenshots.
HTML
The book is written using Microsoft Word. There were multiples reasons for this, including desire to use WYSIWYG editor and to be able to print it (via PDF). And, obviously, we can take DOCX and save it as HTML, right? Not so fast, while Word can save in PDF format that is good enough for printing, it produces HTML from the stone age.
Searching on the Internet reveals that nobody actually knows how to produce acceptable HTML from DOCX. It is quite possible that this book is the first instance where some reasonable results are achieved.
For example, when saving HTML you can select the target browser, assuming that it is IE 6 or less. You can select also the target screen size, assuming that your screen size is one of few carefully chosen for you by Microsoft. Obviously your browser window size cannot be arbitrary? Plus the generated HTML has so much nice details inside like inline styles and other handy stuff.
I tried to use LibreOffice and OpenOffice (GUI and CLI). While the produced HTML is different, it is also not usable. It has even less options when saving HTML than Word.
Finally I switched to Pandoc (CLI). Its HTML code still requires some massaging to be suitable. As I was in a hurry, I wrote a dirty Perl script (dirty script, not Perl) that beautifies the HTML produced by Pandoc.
Another surprise was that the recent Pandoc versions (2.6 currently) fail to process some internal hyperlinks. I had to write another Perl script that figures out correct hyperlinks from ones produced by Pandoc.
BookPile Toolset
All usual staff required for online book is produced by BookPile toolset. It is a simple JavaScript application that I wrote when frustrating search on the Internet did not reveal required tools.
The BookPile takes DOCX file as an input and generates expected suspects like HTML, images, fonts, CSS, and JavaScript. As it is already web chaos there, I decided that one more tool would not hurt.
JavaScript Code
Every book requires good table of content (TOC). HTML book requires interactive one 🙂
While looking on the Internet, I have not found TOC implementation that satisfied me. The one that I wrote from a scratch as a part of BookPile has the following features, some of them usual and some not
- expanding and collapsing individual topics
- expanding and collapsing all topics
- undoing and redoing (so you can safely play with TOC)
- indicator: no subtopics, closed, open, partially open
- shadow “aperture” highlighting topics visible on current page
- TOC width resizing (drag and drop)
Plus some features that are not in this draft but, hopefully, will be ready soon
- stable text position on window resizing (so the same text is still visible)
- hiding TOC
- automatic opening and closing of topics
- configurable themes
- multiple books
The only library that is used in the application is jQuery. It is OK as long as you dance around its bugs. One of the most annoying bugs in my case was that jQuery does not get/set element height/width correctly if the element box sizing is set to border-box. See https://bugs.jqueryui.com/ticket/8932, it is 6-years old!
From implementation point of view, some JavaScript code may be interesting, specifically
- function that combines throttle and debounce
- functions that calculate what topics are visible
- functions that keep visible text on window resizing
Book Build Process
And you thought that JavaScript does not need to be compiled!
Clearly, I use Eclipse IDE for JavaScript and Web Developers to develop the book application. In the case of JavaScript, one of the most important Eclipse add-ons is Tern. Pity, it is showing its age, it seems the author does not have time to maintain it. Alternative new add-on Eclipse Wild Web Developer is not ready for prime time yet, it is too buggy, slow, and lacks Tern features.
For this project, I selected Gulp and Webpack as build tools used by BookPile. As usual, few dozens plugins are required to setup the build process.
Gulp documentation is rather sparse. Figuring out how to use Gulp requires Node.js knowledge. Webpack is better documented. Though, Webpack plugins documentation often lacks details and does not describe enough use cases.
Gulp and Webpack can be used together. But it is an awkward experience – incremental build is limited, no parallelism. In my case, the build process needs to perform the following steps
- produce images and intermediate HTML from DOCX
- build JavaScript code
- build other assets such as more images, CSS styles, and fonts
- generate final HTML containing the book text and the references to JavaScript and CSS
The 1st step can be done in parallel with the 2nd and the 3rd. The last step has to be done after the first three steps.
Unfortunately, the parallelism does not seem possible. Each parallel branch has to use own instance of Webpack, but the last step can use only one Webpack instance. So the last step either cannot get HTML code from the 1st step or cannot get references to JavaScript and CSS.
Using async functions in the build process was a little adventure. Node.js does not allow await statement outside of async functions. So each function that wants to use await must be made async. On another hand, gulp allows task functions to return a stream or a promise but not a promise that is resolved to a stream. As the consequence, it is not possible just to add async keyword to a task function, it is necessary to wrap the task code in a promise that is resolved on the stream end.
So, in summary, the build process is messy, the build configuration is over-complicated. There are no reasonable defaults, you have to write a lot of boilerplate.
Things to Do
Software updates shall be described in more details. What to do when new Java, Eclipse, or Cygwin version is released. Especially, configuring Eclipse to update to the most recent stable release.
Handling of multiple software versions shall be explained. One approach is to have Windows scripts that set PATH to specific Java, Eclipse, and Cygwin versions.
Eclipse basics shall be outlined – things like views, perspectives, menus, help, and preferences.
The book shall describe how to use MinGW that is part of Cygwin
The book contains screenshots from legacy versions of Windows. They shall be replaced with Windows 10 screenshots where it makes sense.
The grammar shall be cleaned.
Additional introduction topics shall be written – book reading requirements, trademark, and license.
The book including its application shall be published to GitLab.