How to import legacy Ada code into GNAT Studio

Incredibly GNAT Studio does not have a menu option to import a mass of existing legacy Ada code and create a project.  I could find nothing on the web.  So here's some instructions.

These notes relate to GNAT Studio Community 2021 (20210423) hosted on x86_64-w64-mingw32, downloaded and installed as part of gnat-2021-20210519-x86_64-windows64-bin.exe.

1.  About the legacy project

Here I am importing the Ada 95 code base for Whitaker's Words, a command-line Latin program normally compiled using gnatmake.  All the .ads and .adb files, and the dictionary files, are in one directory.

Crucially, the "main" file is words.adb.

You compile "words.exe" thus:

gnatmake -O3 words

2.  Create a skeleton project with the same name

Start GNAT studio, and create a new project somewhere on your disk.

Call the project "words" - don't embed spaces -, and call the main "words". This will generate a project, with an empty words.adb file. Adapt it using this example:

with Text_IO; use Text_IO;
procedure words is
begin
   Put_Line("Hello world!");
end words;

Add the with/use, and the put_line.

Then:  Build ... Project ... Build & Run ... words.

Then exit GNAT Studio.

If you open Windows explorer on the directory, you will find a words.gpr, and two directories, obj and src.  src contains the words.adb file.

3.  Copy the legacy code into the project directory.

GNAT Studio works out how to compile stuff from what the words.adb file imports.  So we can take advantage of this by overwriting the dummy words.adb with the real words.adb from our legacy code, and GNAT Studio will work out the dependencies.

Open Windows Explorer, go to your project folder.  There should be two directories, obj and src, and a words.gpr file (which is a text file).

Copy the Whitaker source into the src directory, overwriting the words.adb.

4.  Check the legacy code imports OK

Restart GNAT Studio and reopen your project.  Words.adb should still be open, but it will now contain the legacy code.

5.  Set build preferences

The legacy code will not compile out of the box.

At the menu do Edit ... Preferences.

Change the default builder to gnatmake. I have GNAT installed at the command line - not sure if it uses that.

Then Save.

6.  Set Project Properties and build.

Now alter Edit ... Project Properties... Build ... Switches ... Ada.

Leave the Ada version as "Default", but in Warnings, clear the "Wrong low bound assumption".

Build ... Clean ... Clean All. In the dialog, check the "Only delete compiler generated files" box, and OK.

Build ... Project ... Build All. It should build, although with warnings.

I did get some "non-visible declaration" errors.  I had to alter the first line of word_package.adb, and add "with TEXT_IO; use Text_IO;"  But I didn't have to do more.

7.  Set the Run parameters

My particular legacy project uses dictionary files.  It assumes that these are in the same directory as the .exe. 

Check where the .exe is built in Edit ... Project Properties, Build ... Directories. The Build directory and the Exec directory should both be obj, Artifacts Directory = "(same as object directory)"

The best way to deal with the files is to just copy the data files to the obj directory, and, when you do a Clean, check the "Only delete compiler generated files" option.

So:

• Edit... Project Properties, Build ... Directories. Exec directory = obj (so words.exe is there - you can open a Windows Explorer on the directory and see if it appears).

Then run using:

• Build ... run .. words.  (Use the menu, not the triangular run icon - this doesn't pick up the directory) Be sure "run in executables directory" is checked, then OK.  (You could also check "run in external terminal", if you wanted) 

If you got it right, the program starts up in a window at bottom right, and awaits the command line input.

Note:

You can, instead, tell it to generate the exe in the src folder like this. However this seems to cause problems in Debug mode, so I advise against.

Edit... Project Properties, Build ... Directories. Exec directory = src (so words.exe is there). Ignore the rest and Save.

8. Running the Debugger - general

This is quite horrible for the new user to get to work.  I have written separate instructions on GNAT Studio - How to use the Debugger.  Do this before you try doing it with the legacy code.

9.  Running the Debugger - Legacy code

This is not much harder, in truth. Do it exactly the same way as above.

The main issue is making sure the code can find the dictionary files. 

Make sure you have focus on words.adb.

Initialise the debugger:  Build ... Project ... Build & Debug ... words.  This looks like this:

Note the three breakpoints. I suggest unchecking the first one, set by default, to "every exception". Whitaker handles exceptions, and you'll break at every one otherwise.

The others are set by me.

Once you get here, do Debug ... Run. Leave arguments empty, and check "Use exec dir instead of current dir".  Then OK.

The code will start up Words in a Windows Command window, unlike with Run.

Type "amo" and see what happens.

For those familiar with the code, my first break point was at the start of SEARCH_DICTIONARIES.

And here we are: our legacy code is imported and can be worked with.

Written 26th June 2021.