Migration

This document is only relevant to users of the experimental versions of Tscope (i.e. the versions that were available in the 2003-2004 academic year).

There have been changes to both the Cygwin installation, and to the Tscope API. Both your computer and your own programs will need some updating. How you can do that is explained below. If you choose to do the updates the quick and dirty way, it will only take 5 minutes. Updating the elegant way takes about 20 minutes, but it guarantees that your programs will still compile & run in 2050.

Updating Cygwin

The installation process of Cygwin has changed a lot. You will just have to click some times to install it now, rather than following the steps described in a ten-page manual. With the new installation, you can also compile your programs from within the code editor (now Crimson editor).

The quick and dirty way

The new version of Tscope can run on older installations of Cygwin. You will only need to add some new fonts to your Cygwin installation.

The new fonts can be downloaded here. To install them, put the archive in /usr/local and copy the following commands:

cd /usr/local
tar -xjf fonts.tar.bz2

That's it.

The elegant way

A better way is to remove your old Cygwin installation, and install the new version from scratch. Uninstalling Cygwin can be done the following way:

copy the contents of your home directory (/home/your_login) to a safe place.
open Cygwin for the last time
uninstall ioperm (ioperm -u)
exit the bash shell (exit)
delete the C:\cygwin directory

Once you're done, you can install the new version of Cygwin as described in the download section.

Updating Tscope programs

Some new functions have been added to Tscope, most of the existing functions have new names. There have been no changes to the visible behavior of existing functions, or to their argument list. To update an older program, you will have to replace the old function names with new function names. You should not do that by hand.

If you are using an old Cygwin installation, you'll have to uninstall your old version of Tscope, and install the new version from source.

On a new Cygwin installation, you will also need to install Tscope, but you can choose whether you use the binary or source distribution.

Upgrading older programs to the new api will not be possible forever. Providing backwards compatibility is not only difficult, it also hinders further development. The update scripts will be available for the 2004-2005 academic year only.

The quick and dirty way

The quick and dirty way to update your program is including include/oldscope.h in your program, just after you included Tscope:

#include <tscope.h>
#include <tscope/oldscope.h>

This will define some macros that translate experimental api calls to final api calls at compile time.

There is one change that can't be done by including oldscope.h: the return value of the font functions is now int rather than FONT *. If you use the return value of these functions, replace the FONT * variable you use to catch the return value with an int.

The elegant way

A more elegant, but slightly more difficult way is updating your source code with the exp2final script. The script can be called from anywhere within Cygwin, and takes as argument the source file you want to update to the final api. It searches all experimental api calls in the file, and replaces them with the new calls. Do not leave the file opened in an editor while you do that. Open it afterward to take a look at the changes. If you update foo.c, foo.c will contain the new files, foo.c.old will contain a backup of your old file, in case anything goes wrong.

There are two changes that can't be done by running the exp2final script on your source files.

The return value of the font functions is now int rather than FONT *. If you use the return value of these functions, replace the FONT * variable you use to catch the return value with an int.
The function tg_font_reset does not exist anymore. Replace calls to that function with ts_setfont(0).

top