You become a writer simply by reading and writing. “You learn best by reading a lot and writing a lot, and the most valuable lessons of all are the ones you teach yourself.”
– Stephen King
King’s quote on writing can just as well be applied to Software Development. You become a good software developer simply by reading a lot of well written code and writing a lot of code. There’s no denying this hard truth.
Except that reading code is not a linear process like reading a book where you begin at the first page and end at the last page. Software source code is very non-linear and code components are scattered all over the place. Wrapping your head around large software projects is no easy feat and the fact that most folks aren’t too familiar with cross referencing source code makes matters worse.
This is where Opengrok comes to your rescue. This browser based source code navigation tool makes your life a lot easier when you feel like snooping around a software project that interests you. With Opengrok, you can search for symbols, UI messages, function definitions, variable definitions and files within a software project. In this post I’ll walk you through the Opengrok installation process on Windows and getting a sample software project up and running on Opengrok. Opengrok installation is quite a messy and convoluted process. I hope that this post makes your job a little easier.
1. Download and install Java if you don’t already have Java installed on your machine. To check if you have Java setup on your machine, open up your command prompt and type in ‘java’. If you get the help documentation on the java command, you’re set. If not, head over to Oracle and download the latest Java Runtime Environment. As of August 2017, the latest version was at JRE-8u144. Repeat the command prompt test after installation to make sure Java is now set up.
2. Download and install 7-zip.
3. Download Exuberant Ctags zip for Windows. There is no installation needed here. You just need to unzip the downloaded archive. Decide on a working directory and use that as a destination to unzip all your downloaded archives so you have everything in one place. I usually use C:\Users\<my username> as my working directory. Unzip the ctags zip archive to the working directory.
4. Download Opengrok. Go to Opengrok downloads and get the latest stable release. Ignore the ‘rc’ releases that are release candidates for a future release. Navigate back to older releases until you come across the latest stable release. As of this writing in August 2017, version 1.0 was the latest. Download the .tar.gz package and using an extraction software like 7zip, extract the archive into your working directory. You should finally end up with an Opengrok folder with its subdirectories like so –
5. Download the Apache Tomcat web server to host your Opengrok instance. Go to the Tomcat downloads section and get the latest 64-bit Windows zip. I have Tomcat 9 on my machine. Once downloaded, extract the zip into your working directory. There is no installation to be done here.
6. Before you can launch your Tomcat web server, you would need to set up two environment variables – CATALINA_HOME and JRE_HOME. Hit the window button and type “Environment variables” to pull up the environment variables window. Now under the system variables section, press New and add the two new variables. CATALINA_HOME should point to the Apache Tomcat directory and JRE_HOME should point to the path of your JRE.
7. Verify that you can get your Tomcat server to run by navigating to apache\bin and double clicking on startup.bat. If everything is set up correctly, you can expect to see a Tomcat startup window that looks like the one below. Leave it running.
Now in your browser, type in http://localhost:8080 and you should see the below page.
As the webpage says, Congratulations for having come this far!
8. Go to Opengrok > lib and extract source.war archive into a folder named source. You can use 7zip to extract the war archive. After this extraction, move the entire ‘source’ folder into the apache\webapps folder.
9. We’re now pretty much finished with setting up our Opengrok environment. We can now proceed to download some source code from a remote repository and load it up onto Opengrok to begin fooling around. I’ll use the open source project ‘Memcached’ as an example. Head on over to the project’s Github and get the source either by cloning the repository if you have your git environment setup, or downloading a zip of the source here. I usually direct my source clones or downloads into a dedicated folder C:\OpenSource.
10. Open up your command prompt and navigate to your Opengrok directory. Type in the below command:
java -jar lib\opengrok.jar -W .\configuration.xml -c <working directory>\ctags.exe -P -S -v -s C:\OpenSource -d .\grokdata
This will kick off the indexing job for all the source code items in the directory you specified in the above command. In the example screenshot below, every eligible item under C:\Opensource will be indexed. You will end up with a configuration.xml file created under the Opengrok folder once the indexing job completes.
11. Go to apache\webapps\source\WEB-INF\web.xml and edit the “CONFIGURATION” tag in the xml file to point to the generated opengrok\configuration.xml file. I use notepad++ to edit these XMLs.
12. Launch your browser and get to http://localhost:8080/source.
You’re now in the big leagues! With Opengrok successfully installed, you can now download the source code of projects that interest you and simply run the indexer on the root folder that houses all your projects. The indexer sometimes takes a while to finish up on very large projects like the Linux kernel when you run it for the first time on a newly downloaded project. If you modify the source code and would like to see the changes up on Opengrok, run the indexer again and reload the web page. Subsequent indexings should be fairly quick.
If you like to keep your system lean like I do, you can now uninstall 7zip if you wish.