Indexing Workspace
It's time to create our first program graph (index)! Remember, a program graph is an abstraction to represent the essential aspects of a program's syntax and semantics (structure, control flow, and data flow), which are required to reason about software. Atlas uses a heterogeneous, attributed, directed graph data structure, which will become clear as we progress through upcoming tutorials.
For this tutorial series we have created a few simple projects to get you started learning Atlas. The Eclipse projects are available on Github at https://github.com/EnSoftCorp/LearningAtlas.
On your command line change your current directory to the git folder we made in the Installing Atlas section. Next, clone a copy of the repository by running the following command on your command line.
cd <my_path>/Atlas/git git clone https://github.com/EnSoftCorp/LearningAtlas.git
If you need to install Git on your system visit http://git-scm.com/downloads. Alternatively you could download a zip file of the latest LearningAtlas repository archive here https://github.com/EnSoftCorp/LearningAtlas/archive/master.zip.
Contents
Step 1) Create/Import Projects to Index
Import an Eclipse Java project into the workspace by navigating to File > Import > General > Existing Projects into Workspace and browsing to an existing project. If the project is a zip archive, you will want to check the Select archive file radio button, otherwise check the Select root directory radio button. Click Finish to import the projects into the workspace.
Alternatively you could create a new Java project by navigating to File > New > Java Project and creating a new Java project. If you create a new Java project, you will want to add some Java code so you have something to index and analyze.
For this tutorial import the HelloWorld project you just downloaded into the Eclipse workspace.
Step 2) Set Indexing Preferences
If you haven't already check your Indexing Preferences. For this tutorial let's use the Index only used classes in jars indexing option.
Step 3) Select Projects to Index
Atlas will index any open projects in the Eclipse workspace that you have selected for indexing. To select and deselect projects for indexing navigate to Atlas > Manage Project Settings. The Do no index pane on the left lists projects that will not be indexed, and the Index pane on the right lists projects you wish to have indexed. Be mindful of your analysis task and include any necessary dependent projects and exclude projects you don't need or projects that should not be analyzed (ex: projects with analysis utilities you will use during your analysis).
In this tutorial, make sure the HelloWorld project is selected for indexing. The screenshot below shows that some additional projects (the toolbox.analysis and toolbox.shell projects) will not be indexed, but the HelloWorld project will be indexed. Note that Atlas conveniently provides a memory estimate for the projects you are about to index. If you need adjust your Eclipse Memory Settings to accommodate the size of the index (program graph), then you should do so now.
If you encounter a situation where you want to exclude some packages from indexing in a project marked for indexing, you can set an index filter. To set an index filter navigate to Atlas > Mapping Filters, add a filter pattern and press OK. The screenshot below shows a filter to filter the packages in the Android support library (version 4) to exclude them from the index.
Step 4) Run Indexer/Load Index
Now that you've selected your indexing preferences and the projects to index, let's start an indexing job. Simply navigate to Atlas > Re-Map Workspace. After triggering an index, an Eclipse job to index the selected projects will start. You can monitor the progress in the bottom right hand area of the Eclipse window or by opening the Progress view. Top open the Progress view navigate to Eclipse or Window > Show View > Other... > General then select Progress and press OK.
After indexing is complete, you can optionally save an index at anytime by navigating to Atlas > Save Current Code Map, specifying a file name and location, and pressing Save. Depending on your Indexing Preferences Atlas may have already cached a copy of the current index to disk.
If you've previously saved or automatically cached an index you can load the index back into memory at anytime by navigating to Atlas > Save Current Code Map, selecting the saved index file, and pressing Open. You should also make sure you have the same project you used to create the loaded index open in the workspace or source correspondence will fail later.
Step 5) Perform Analysis
Congratulations, you've just generated a program graph (index) that is ready for analysis. You can now run queries on the Atlas Shell.
