You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucenenet.apache.org by rc...@apache.org on 2022/01/07 22:06:31 UTC
[lucenenet] branch master updated: Add How to Setup Java Debugging page
This is an automated email from the ASF dual-hosted git repository.
rclabo pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/lucenenet.git
The following commit(s) were added to refs/heads/master by this push:
new a3852df Add How to Setup Java Debugging page
a3852df is described below
commit a3852df9cc6bf38717342a222dbc813444c1d125
Author: Ron Clabo <ro...@GiftOasis.com>
AuthorDate: Fri Jan 7 17:01:35 2022 -0500
Add How to Setup Java Debugging page
---
.../how-to-setup-java-lucene-debugging.md | 530 +++++++++++++++++++++
websites/site/contributing/toc.yml | 4 +-
websites/site/lucenetemplate/styles/main.css | 6 +-
3 files changed, 538 insertions(+), 2 deletions(-)
diff --git a/websites/site/contributing/how-to-setup-java-lucene-debugging.md b/websites/site/contributing/how-to-setup-java-lucene-debugging.md
new file mode 100644
index 0000000..19b8bba
--- /dev/null
+++ b/websites/site/contributing/how-to-setup-java-lucene-debugging.md
@@ -0,0 +1,530 @@
+# How to Setup Java Lucene 4.8 Debugging
+
+---
+
+## Introduction
+
+Sometimes when porting Lucene 4.8 to Lucene.NET 4.8 it is helpful, or even necessary, to be able to watch Java Lucene 4.8 run in a development environment. The goal of this document is to help walk you through the process of setting up such a development environment on Windows 10.
+
+The Java Lucene 4.8 repository indicates that the following development environments are supported:
+
++ Eclipse - Basic support (help/IDEs.txt).
++ IntelliJ - IntelliJ idea can import the project out of the box.
++ Netbeans - Not tested.
+
+In this document however, we will be using Eclipse because it’s open source and widely used. Because Java Lucene 4.8 uses an old version of the Java JDK that has known security issues, the approach we take here is to setup a virtual machine vis VirtualBox to quarantine our use of the insecure JDK.
+
+
+## Setting up VirtualBox
+
+### Introduction and Background
+We don’t need to setup network access for VirtualBox for our needs and since the old JVM required to run Lucene 4.8 has security issues, it’s safer not to give VirtualBox network access. And since VirtualBox can run in a window, it means that when running it that way you will still have access to the internet and a browser on your main OS for doing coding research and such.
+
+### Download Virtual Box
+You can get the installer from [https://www.virtualbox.org/wiki/Downloads](https://www.virtualbox.org/wiki/Downloads) . On that page download the binary version for **Windows hosts**.
+
+After downloading the installer, run it.
+
+<img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install01.png'>
+
+Then you will get the dialog below where you can specify the location where you want to install the VM on your machine.
+
+<img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install02.png'>
+
+Then you will get the dialog below where you can specify the location where you want to install the VM on your machine.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install03.png'>
+
+
+Then as you click next you will eventually come to this dialog:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install04.png'>
+
+You may get some security warnings. If so, click Install.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install05.png'>
+
+Then when the install is done you will see a dialog similar to the one below.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box-install06.png'>
+
+
+### Configuring VirtualBox
+Clicking the Finished button in the prior dialog will launch VirtualBox, or you can launch it manually via the programs menu in Windows 10 as you would with any other “application.”
+
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box02.png'>
+
+### Default Machine Folder
+To change the location where the machine will be stored, click the Preferences icon in the main window or go to File menu and select Preferences. Then in the dialog that opens in the General tab you can change the Default Machine Folder by selecting Other… in the drop down as I have done here.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box03.png'>
+
+### Create Windows 10 Installation Media
+In this walkthrough we will be running Windows 10 in the VM. Note that to do this one needs a 2nd Windows 10 license other then the one installed on the physical machine. So two licenses are needed, one for the physical machine OS install and one for the VM OS install. If you don’t have a spare Windows 10 license to use in the VM you can consider installing ubuntu or other open source OS. Next to run Windows 10 in the VM we much download and create Windows 10 installation media. Thi [...]
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box04.png'>
+
+Then run the exe that is downloaded. You need to agree to the terms if they are acceptable to you. Our goal here is to create an iso file that we can use to install Windows in the VM. We don’t need that iso file burned to a cd, just having it saved to the computer is fine.
+
+In this dialog select “Create installation media”
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box05.png'>
+
+On this dialog select “ISO file”
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box06.png'>
+
+Then in the dialog that comes up pick a place on the computer to save the ISO file
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box07.png'>
+
+And then it will begin downloading the file and displaying a progress indicator. Once the file is downloaded, we have now have the ISO file we need for installing the OS inside of VirtualBox.
+
+Once that’s done, you can click Finished in the dialog that comes up since we don’t need to burn this ISO file to a dvd. Having it on the hard drive is fine.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box08.png'>
+
+### Creating a Virtual Machine
+Click the New button in the main dialog of VirtualBox Manager.
+Fill out the info in this dialog:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box09.png'><br>
+ And this one:<br>
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box10.png'><br>
+ And this one:<br>
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box11.png'><br>
+ <br>
+The default choice below is fine:<br>
+<br>
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box12.png'>
+
+In the following dialog “Dynamically allocated” is fine. Then in the dialog after that set the max size.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box13.png'>
+ <br>
+ Then it will look something like this:
+ <br>
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box14.png'>
+
+ Back in settings click on storage, on the left, then click on Empty in the storage devices, this represents the CD rom.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box15.png'>
+
+Now click the little disk drop down next to the Optical Drive label. From that menu select “Chose a Disk File…” and select the windows ISO file you previously downloaded.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box16.png'>
+
+
+Now it’s like that Windows Install DVD is installed on our virtual computer. (See below)
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box17.png'>
+
+Since by default the VM is setup to boot from the virtual optical drive (as well as the virtual hd) we can click start in the VirtualBox Manager to begin the Windows 10 Install into the VM.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box18.png'>
+
+ Then select the startup disk:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/virtual-box19.png'>
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install01.png'>
+
+Click next in the dialog above, then install now. Then in the window below key in your product key or click I don’t have a product key.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install02.png'>
+
+Click agree on the license terms if you agree.
+Then in the dialog below click “Custom” since this is a new install not an upgrade.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install03.png'>
+
+It will then show the unallocated space of the virtual drive we setup earlier. Select that as the place to install the OS and click next
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install04.png'>
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install05.png'>
+
+ And then:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install06.png'>
+
+Then go through all the screens for the standard Windows setup and after that you will probably see the screen below.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install07.png'>
+
+And then finally we have windows running in the vm, and in the screenshot below I launched edge to show that networking is working in the VM too.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/windows-install08.png'>
+
+## Installing Eclipse 4.6
+
+Source of download https://wiki.eclipse.org/Older_Versions_Of_Eclipse. We want “Eclipse Neon Packages (2016 - v 4.6.0)” This version goes by the name “neon r” and it’s page is here: https://www.eclipse.org/downloads/packages/release/neon/r
+
+We want the 2nd package below, “Eclipse IDE for Java Developers” so download that, in my case the x86_64 link.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/eclipse01.png'>
+
+Once that zip file downloads, then extract the contents into a folder.
+
+
+
+## Installing Java 8
+
+Lucene 4.8.0 uses Java 8 to run according to the build.xml file but Eclipse needs Java 8. And Eclipse can use Java 8 to emulate Java 7 when running Lucene.
+So we will need to install “**Java SE Development Kit 8u25**” into our VM which can be downloaded from https://www.oracle.com/java/technologies/javase/javase8-archive-downloads.html You will notice the following warning on that page. This is why we chose to work inside a VirtualBox.
+
+> **WARNING**: These older versions of the JRE and JDK are provided to help developers debug issues in older systems. **They are not updated with the latest security patches and are not recommended for use in production.**
+
+You will need to scroll down a ways on the page to find “**Java SE Development Kit 8u25**” or better yet search the page for 8u25. Then download the Windows x64 one jre-8u25-windows-x64.exe
+Download and run that jdk-8u25-windows-x64.exe file that in the VM.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-java8-01.png'>
+
+I just took all the default options and had it do the install.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-java8-02.png'>
+
+ And then:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-java8-03.png'>
+
+ And then:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-java8-04.png'>
+
+
+
+Eclipse will now run but we have more to install before can load Lucene 4.8.
+
+
+
+## Installing Apache Ant
+
+Use version 1.9.7 if you can find it, but 1.9.15 should work. But you MUST the 1.9 branch of Apache Ant, not a newer one. Ant is currently running two branches, 1.9.X and 1.10.X.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant01.png'>
+
+You can get version 1.9.7 here: https://archive.apache.org/dist/ant/binaries/ The actual download link for the zip version from that page is https://archive.apache.org/dist/ant/binaries/apache-ant-1.9.7-bin.zip
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant02.png'>
+
+You’ll have to unzip the downloaded `apache-ant-1.9.7-bin.zip` file.
+
+The unzipped folder will need to be moved to a place of your choosing where you want ant to live. In my case I created a folder called “Apache Software Foundation” inside the “Program Files” folder and placed it there. So my path was `c:\Program Files\Apache Software Foundation\apache-ant-1.9.7` Directions for installing Ant are on this page under “The Short Story” https://ant.apache.org/manual/install.html
+
+I typed “Environment Variables” into windows search and used that to open the System Properties window. Then clicked the Environment Variables button.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant03.png'>
+
+ And then:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant04.png'>
+
+
+In here we can set the Environment Variables we need.
+See this page for more details of what we need to do:
+https://ant.apache.org/manual/install.html#setup
+
+From that Page:
+1. Add the bin directory to your path.
+2. Set the ANT_HOME environment variable to the directory where you installed Ant. On some operating systems, Ant's startup scripts can guess ANT_HOME (Unix dialects and Windows NT descendants), but it is better to not rely on this behavior.
+3. Optionally, set the JAVA_HOME environment variable (see the Advanced section below). This should be set to the directory where your JDK is installed.
+
+Adding the Bin directory to my path environment variable:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant05.png'>
+
+ And then:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant06.png'>
+
+Then adding the ANT_HOME environment variable
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant07.png'>
+
+
+
+Then adding the JAVA_HOME environment variable
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-ant08.png'>
+
+
+
+## Installing Apache Maven
+
+Use version 3.8.1. https://maven.apache.org/download.cgi The installation process is basically the same as Apache Ant. This is the Java equivalent of NuGet.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-maven01.png'>
+
+ Then scrolling down the page:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-maven02.png'>
+
+We are going to download `apache-maven-3.8.1-bin.zip`
+Move the folder out of the zip and into the location by the apache ant folder.
+
+“install” instructions are here: https://maven.apache.org/install.html
+
+Add the `bin` directory of `apache-maven-3.8.1 to` the `PATH` environment variable
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-maven03.png'>
+
+
+Then open a command prompt via cmd.exe and type mvn –v to confirm that the path is setup correct. Output should look something like:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-apache-maven04.png'>
+
+
+## Installing Git
+
+https://git-scm.com/download/win
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-git01.png'>
+
+Of the choices above I chose “64-bit Git for Windows Setup.” Download and run the installer. Agree to the license, pick a directory to install it in, I kept the default, I also kept the default components in the dialog below:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-git02.png'>
+
+ Next:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-git03.png'>
+
+In the dialog avove I ched the default Git editor from vim to Notepad. Pick whatever you like. In general for the other dialogs I kept the defaults including on this one
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-git04.png'>
+
+Next:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/install-git05.png'>
+
+## Clone Lucene 4.8 Repo to VM Drive
+
+Shad says: The top level thing in Java Eclipse is called a workspace. I haven't really researched exactly what a workspace is, but it can have more than one java project in it. When you clone the repo, you will put it in your repos folder. But there needs to be another folder for Java to consider a workspace. Maybe in reality it can be the same folder, but I haven't worked out how to do that.
+
+So create two folders one for the cloned repo and one for the Eclipse workspace. In my case I created these directories to satisfy that:
+
+C:\Users\Ron\source\eclipse_workspaces\lucene_workspace
+C:\Users\Ron\source\repos\lucene
+
+### Why not clone the code directly from Java Lucene Repo?
+It turns out that it’s no longer possible to directly compile the Lucene 4.8 code obtained from the Java Lucene Repo without modification. Unlike NuGet which makes old versions available forever and is always online, Maven has lots of mirrors that may cease to exist at some point, and that is what’s happed, so the configuration in the Java Lucene 4.8 Repo is out of date and no longer builds.
+
+In addition, Java 8 (which we need for Eclipse) detects an error in the code that Java 7 did not, so the build doesn't complete. It is due to some fields that are marked final that are disposed at the end of the constructor (so they really don't need to be fields). Taking the final keyword off of the field removes the error. So, the project has to be modified slightly so all of this can happen.
+
+### Where can we get Java Lucene 4.8 code that compiles?
+There is a fork of the Java Lucene Repo at https://github.com/NightOwl888/lucene that includes modifications to update the Maven and ant files so that the code will still compile.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code01.png'>
+
+Steps to Clone it into the VM
+
+Open the folder that will contain the clone folder and then right click in there and select “Git Bash Here” from the content menu.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code02.png'>
+
+Then in the Bash window type the following (where lucene-4.8.0 is the name we want it to use for the destination folder):
+
+`git clone https://github.com/NightOwl888/lucene.git lucene-4.8.0`
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code03.png'>
+
+This process will take several minutes because the repo it over 1GB in size. Here is a view of the Bash window in the middle of the clone operations:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code04.png'>
+
+Once that completes Lets checkout the branch, in the Bash window type:
+
+`cd lucene-4.8.0`
+
+followed by
+
+`git checkout releases/lucene-solr/4.8.0/update`
+
+You can see the name of the branches here:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code05.png'>
+
+Here’s what I looked like when the clone was done;
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code06.png'>
+
+ Now cd into the directory that was created as part of the clone operation by typing the following Base command: cd lucene-4.8.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code07.png'>
+
+In windows, this is what the directory looks like:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/where-can-we-get-the-code08.png'>
+
+
+## Downloading the Project’s Dependencies
+
+### Boostrap ant
+First we need to get ant bootstrapped.
+Here is some background on Maven and Ivy from the web:
+> Apache Maven is a software project management and comprehension tool, whereas Apache Ivy is only a dependency management tool, highly integrated with Apache Ant™, the popular build management tool. Source: https://ant.apache.org/ivy/m2comparison.html
+
+From inside of the lucene-4.8.0 directory, run this Bash command
+
+`ant ivy-bootstrap`
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/download-dependencies01.png'>
+
+What it just did is downloaded the ~/.ant/lib/ivy-2.3.0 file
+
+
+### Use Ant to Download Project Dependencies
+
+Apache Lucene has a ton of 3rd party dependencies. The next step is to have maven download all those dependencies. This can take a while depending on your machine and internet connections.
+To see a list of the dependencies look at **lucene/ivy-versions.properties** file.
+
+We should now be setup to build. So run the following Bash command:
+
+`ant eclipse`
+
+Example screenshot while ant is doing it’s work:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/download-dependencies02.png'>
+
+In my case it took about 10 minutes for ant to download all the dependencies. The bash window then looked like this:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/download-dependencies03.png'>
+
+## Using Eclipse
+
+### Getting Stared with Eclipse
+Now we need to open eclipse and create a workspace. So we use windows to go to the eclipse folder which in my case is here C:\Program Files\eclipse and we double click on eclipse to run it.
+Eclipse will prompt you to create a workspace.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse01.png'>
+
+Browse to find the location we created earlier to house our lucene workspace folders and create a folder in there for this version of lucene. I called my lucene4.8.0_workspace as you can see in the screenshot below.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse02.png'>
+
+And after a few more seconds Eclipse will open in a window:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse03.png'>
+
+
+We can zoom to take up the whole VM screen space.
+
+Then click the **Create new Java project** in the welcome screen.
+
+1) Provide a Project name, in my case Lucene4.8.0,
+2) Then uncheck the “Use default location” check box.
+3) Then use the browse button to specify the **location of the git repo clone.**
+
+So the dialog will then look something like this:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse04.png'>
+
+Click the Next button.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse05.png'>
+
+Then click the Libraries Tab and scroll down and select the JRE System Library
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse06.png'>
+
+Then click the Edit button.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse07.png'>
+
+Then set the System Library radio button to “Workspace default JRE” if it’s not selected already. Then clicked the Finish button on that dialog, and then click the Finish button on the other dialog.
+
+Then expand the window to take up the whole VM and you will see a build progress indicator in the lower status bar. The project is now building in the background.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse08.png'>
+
+Zoomed in to see the Building workspace message better in the status bar
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/using-eclipse09.png'>
+
+Once the build complete my screen looked like the screenshot below. There were a lot of code warnings but no errors.
+
+### Debugging With Eclipse
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse01.png'>
+
+Now Click the little icon to expand the packages under Lucne4.8.0 in the package explorer
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse02.png'>
+
+Then scroll down to **lucene/analysis/phonetic/src/test** and select it
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse03.png'>
+
+Then right click it and select Run As Junit Test
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse04.png'>
+
+ Then
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse05.png'>
+
+The above screen shows it ran the 35 tests in 32.196 seconds and all of them passed. Yea.
+
+Click on Package Explorer tab (by the Junit tab) and expand the phonetics/src/test item.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse06.png'>
+
+Double click the line highlighted above and it will open the code for that test.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse07.png'>
+
+Then double click on line 108 and it will set a breakpoint.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse08.png'>
+
+Now right-click on testEmptyTerm (make sure it is still highlighted) and click Debug As > JUnit Test
+
+You will get this dialog:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse09.png'>
+
+Eclipse has a different "perspective" for debugging than for browsing projects, similar to in VisualStudo. However, it gives you a choice whether you want to use it or not. Click yes, but don’t choose to remember the setting, because it’s not clear where to find it again.
+
+And it will launch into the debugger layout and be waiting on the breakpoint.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/debugging-with-eclipse10.png'>
+
+If you hover the debugger icons you will see that
+
+Resume is F8<br>
+Step Into is F5<br>
+Step Over is F6<br>
+Step Return is F7<br>
+
+So it works much like VisualStudio but the F key configuration is different. You can of course just click the icons at the top of the window, or goggle and there is probably a way to change the F key configuration for the debugger actions.
+
+<font style="font-weight:bold; font-size: 17px">There ya go. You are now in Eclipse, and able to run the debugger for Lucene 4.8 Java code.</font>
+
+<font style="font-weight:bold; font-size: 20px">How cool is that?!</font>
+
+ You’re welcome, and a big shout out to NightOwl888 who blazed this trail for us all.
+
+
+## Two More Helpful Tips
+
+### Cloning the Local Repo
+It is sometimes useful to create a clone in another versioned directory and then checkout the corresponding branch.
+
+Basically, it is cloning the whole repo again in the subdirectory lucene-4.8.1. Then to match that version number, we checkout the branch that matches it. Now, if we were doing that from the original lucene repository we would typically checkout the tag that corresponds to the release rather than a versioned branch. But since the maven dependencies are all broken, we have our own branches that patches the release that we have ported changes from.
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/clone-local-repo01.png'>
+
+
+Zommed in a bit more:
+
+ <img src='https://lucenenet.apache.org/images/contributing/java-lucene-4_8-setup/clone-local-repo02.png'>
+
+
+When you clone the repository locally, it only shows the default branch that you have pulled (unless you use the switch to pull all of them). But Git keeps track of the remote branches as well as the local ones on your local copy (that is, all of the remote branches that you have called git fetch or git pull on).
+
+"git branch -r" shows a list of all of the remote branches that you have pulled. "git checkout releases/lucene-solr/4.8.1/updated" command is a shortcut for creating a branch based off of the remote. It won't work if you have 2 remotes that have a branch with the same name - in that case you would need to specify the remote name, too. https://stackoverflow.com/questions/24301914/how-to-create-a-local-branch-from-an-existing-remote-branch Of course, all of the posts on that SO question [...]
+
+
+### Disable Java Update Checker
+One more thing you might want to do is to disable the Java update check so it doesn't accidentally get rid of Java 8. See: https://thegeekpage.com/turn-off-java-update-notification-in-windows-10/
diff --git a/websites/site/contributing/toc.yml b/websites/site/contributing/toc.yml
index a262628..284d6d3 100644
--- a/websites/site/contributing/toc.yml
+++ b/websites/site/contributing/toc.yml
@@ -1,4 +1,4 @@
-- name: Community Links
+- name: Community Links
href: community-links.md
- name: Mailing Lists
href: mailing-lists.md
@@ -12,5 +12,7 @@
href: current-status.md
- name: Making a release
href: make-release.md
+- name: How to Setup Java Debugging
+ href: how-to-setup-java-lucene-debugging.md
- name: Wiki
href: wiki.md
\ No newline at end of file
diff --git a/websites/site/lucenetemplate/styles/main.css b/websites/site/lucenetemplate/styles/main.css
index 52cb883..af4967f 100644
--- a/websites/site/lucenetemplate/styles/main.css
+++ b/websites/site/lucenetemplate/styles/main.css
@@ -1,4 +1,4 @@
-/*
+/*
* Licensed to the Apache Software Foundation (ASF) under one
* or more contributor license agreements. See the NOTICE file
* distributed with this work for additional information
@@ -80,6 +80,10 @@ header ul.navbar-nav {
}
}
+.article img {
+ margin:15px 0 30px 0;
+}
+
.sidefilter {
top: 120px;
}