Setting Up Eclipse (Any OS)

Update: The Preconfigured CorsixTH Eclipse Project has been removed from the repository. Please make your own project instead.

Page Contents

1. Install A JRE
2. Install Eclipse
3. Install The Lua & C++ Plugins
4. Import A Preconfigured CorsixTH Eclipse Project
5. Setup Eclipse For Debugging CorsixTH's Lua Scripts At Runtime
6. Modify Debugger.lua To Make It Support Lua 5.3
7. Customizing A Perspective
8. Making Eclipse Use Two Space Indentations
9. Eclipse Programming Tips

Debugger Tutorials

Install A Java Runtime Environment

Eclipse is a Java program so whatever operating system your using you will need to install the Java Runtime Enviroment to run it.

If your using a Linux distribution such as Ubuntu you should ideally download and install the JRE from a repository using your distribution's package manager.

Install Eclipse

Eclipse can be downloaded from here. You will see there's multiple release to choose from each coming with a different set of pre-installed plugins.

If you choose the Eclipse release for C++ developers you won't have to install the "C/C++ development" plugin later (a very quick & easy process) for working with CorsixTH's Source code.

To install Eclipse simply extract it to the directory where you want Eclipse to be installed.

Install The Lua & C++ Plugins

1. Start Eclipse.
2. When your asked to select a workspace to load I recommend you create a workspace for just storing your CorsixTH project so that your tabbed views of CorsixTH files your editing will be re-opened whenever you switch back to this CorsixTH workspace:
3. In Eclipse's "Help" drop down menu click on "Install New Software".
4. In the "Install New Software" window use the "Work With" drop down box to select the plugins repository for your Eclipse version and then open the "Programming Tools" category.
5. In this plugin category tick these two plugins:

• Lua Developments Tools
• C/C++ Development Tools

1. Now install these plugins by clicking on the "Next" button and then doing their install steps.
2. When Eclipse has been restarted click on the "Open Perspective" toolbar button and then open the Lua perspective:
3. Finally do this for the C++ perspective as well.

▴Back to contents

Import A Preconfigured CorsixTH Eclipse Project

1. In Eclipse's "File" drop down menu click on: "Import"
2. In the Important window's General category click on "Existing Projects Into Workspace"
3. Click on the "Browse" button for the root directory's path and then choose: .../Github/CorsixTH/Eclipse/Luna/CorsixTH
4. After this path has been set click on the "Finish" button:

▴Back to contents

Setup Eclipse For Debugging CorsixTH's Lua Scripts At Runtime

1. In Eclipse's "Run" drop down menu click on: "Debug Configurations"
2. Now double click on "Lua attach to application".
3. Name this debug configuration.
4. Set the "Timeout(s)" time to 600 seconds.
5. Click on the Apply button.
6. Download debugger.lua and then put it into your CorsixTH/Lua folder. The version downloaded with the link in Eclipse Mars doesn't work so the version I've provided a link to here is the Luna version which does work. I reported this problem and its now been fixed in the LDT plugin's master branch.

▴Back to contents

Modify Debugger.lua To Make It Support Lua 5.3

NOTE: Breakpoint use conditions don't work with Lua 5.3 but hit count use conditions do work.

--FIXME: remove this hack as soon as luasocket officially support 5.2
if _VERSION == "Lua 5.2" then
  table.getn = function(t) return t and #t end
end

1. Remove the above statements at line 167.
2. Use the text finding tool in the program your editing this script with (CTRL + F) to find all the Lua 5.2 compatibility IF statements and make them support Lua 5.3 by adding this condition:
   or _VERSION == "Lua 5.3

▴Back to contents

Customizing A Perspective

Eclipse allows it users to fully customize a perspective's interface by moving, opening and closing views.

So in the Lua perspective you may prefer your "Outline" view and "Script Explorer" view to not split their interface panel between them. To change this simply drag the tab for the "Outline" view next to the tab for the "Script Explorer" view.

I find the "Bookmarks" view helpful: to add this view to a interface panel click on: .

To bookmark a statement right click on the grey space left of it and then click on "Add Bookmark". To jump your script editing view to a bookmarked statement double click on its name in the Bookmark view.

▴Back to contents

Making Eclipse Use Two Space Indentations

With the CorsixTH coding standard being two space indentations for Lua code and four space indentations for its source code changing this setting is useful because it will allow you to insert two spaces in a single key press for a single line or multiple selected lines using your tab/indentation key and by holding shift you will be able to remove two space indentations for one or more lines.

1. In the "Window" drop down menu click on "Preferences".
2. Then open the settings for: General > Editors > Text Editors:

These settings can't be project specific.

▴Back to contents

Eclipse Programming Tips

• CTRL + L: Will move your script editing view to the statement which has the line number you provide.
• CTRL + F: Will open the find & replace tool for a file your editing.
• CTRL + H: Will open Eclipse's multiple file search tool.
• CTRL + /: Comment/Uncomment selected statements.
• CTRL + Q/Mouse's back button: Last edit location.
• You can jump your script editing view to a function/variable's declaration by clicking on its name in the "Outline" view:

• In the "Problems" view you can go to a detected problem's statement by double clicking on it.

You can also change the scope of what problems are listed at once:

▴Back to contents