Working with Large Codebases

Working with Large Codebases

Atlas is great for learning a new codebase and can even help with comprehension of large codebases. This page explains how to configure Atlas to be able to process as much of the codebase as possible. There are two ways to configure Atlas for processing large codebases: increase the amount of memory available to Eclipse or limit the amount of code that is indexed.

How to increase the amount of memory available to Eclipse

Eclipse, like any other Java program, is limited by the amount of memory that is given to the JVM in which it runs. In most Java programs, this memory limit would be set by adding the -Xmx command line argument. For example, adding -Xmx512m to the java command line would set the maximum heap size to 512 MB.

Eclipse Memory Settings

With Eclipse, the -Xmx value is set in the eclipse.ini file that sets many other configuration options for Eclipse. In order to allow Atlas users to easily change the maximum (Xmx) and minimum (Xmx) heap size settings, we have created the “Eclipse Memory Settings” dialog (opened by clicking Atlas > Eclipse Memory Settings). This dialog allows the user to check the current maximum and minimum heap size settings and to edit them while running Eclipse. The dialog can be found in the Atlas menu of the Eclipse main menu. When the dialog is opened it will display the current values for the maximum and minimum heap size values. The values will be in KB, MB, or GB, depending on how they are stored in the .INI file. The values can be edited and then will be saved in the .INI file after the "OK" button is clicked. A restart of the workbench will be necessary to reflect the new values in eclipse.ini.

1. Open the Eclipse Memory Settings dialog by clicking on Atlas > Eclipse Memory Settings in the Eclipse main menu.
2. Choose the correct eclipse.ini file for your current instance of Eclipse (it should be automatically set to the current eclipse.ini file).
3. Increase the maximum memory settings. You may also increase the minimum memory setting to require the JVM to start with that much memory allocated but it is not necessary. See the section on Memory Guidelines for estimates of memory requirements for different size codebases.
4. Click “OK”.
5. If you are running Windows, Atlas may need to request Administrative access to edit the eclipse.ini
6. Eclipse will need to restart to reflect the change in memory settings

How to index portions of the codebase

Manage Project Settings

The “Manage Project Settings” dialog in Atlas (opened by clicking Atlas > Manage Project Settings) is used to determine which projects should be indexed by Atlas. This dialog provides an estimate with each project of the amount of memory that will be required to index it. It also offers a running total of the estimates for the projects that will be indexed and compares it to the amount of memory available to Eclipse. This dialog is a helpful tool to determine which projects can be indexed together in order to best leverage the amount of memory available. The amount of memory listed is only an estimate; the real amount of memory required will depend on the style and complexity of the code.

1. Open the Manage Project Settings dialog by clicking on Atlas > Manage Project Settings in the Eclipse main menu.
2. Select the projects to be indexed by moving them to the right column.
3. Ensure that the total memory estimate is less than the memory available. Remove extra projects if the memory estimate is too high.
4. Click “OK”.

Index Filters

If a project that you would like to index includes packages that you don’t want to index (e.g. a package with test files), these packages can be filtered out of the indexing process using the “Index Filters” dialog (opened by clicking Altas > Index Filters). This dialog is used to create String matching filters that exclude any package with a name that matches the filter. The filtering feature uses the same String matching mechanism as the Search dialog in Eclipse. The filter String can be a regular string with * and ? as wildcards or it can be a Regular Expression.

1. Open the Index Filters dialog by clicking on Atlas > Index Filters in the Eclipse main menu.
2. Type the String matching filter in the text box.
3. Choose the correct values for “Case sensitive” and “Regular expression”.
4. Click “Add” to add the filter to the list.
5. Filters can be edited by selecting the desired filter and clicking on the “Edit” button.
6. Filters can be removed by selecting the desired filter and clicking on the “Remove” button.
7. Click “OK” to apply changes.

Low Memory Warning

While the index is running, Atlas will monitor the amount of memory that Eclipse is using and compare it to the amount of memory available to Eclipse. If the amount of memory being used becomes too high, a warning dialog will appear and ask if the user would like to cancel the indexing process or let the process continue. The indexing process may still complete with the amount of memory available, but it will most likely run much slower due to frequent Garbage Collection by the JVM.