Porting Amaya to a new platform

This document explains the main steps requited to port Amaya to a new platform. This should be quite straightforward as long as the following applies :

• The systems is 32-bit, as the Thot library has not yet been tested/ported to 64-bit systems.
• The system offers the Posix system interfaces, at least for the libc and filesystem access calls.
• The X11 (R5 or R6) and Motif (1.2.x or 2.0) interfaces are available.
• A correct C compiler (preferably ANSI compliant) is available.

The Amaya team is porting Amaya to the Windows 32 bit API, but this is not finished yet. The current code merge both the Unix/X-Window code and the Windows one.

Here are the steps needed to build Amaya for a new platform :

1. Find a name for the Platform/OS, update the Thot/batch/MachineType to return this name, noted Target in the following.
2. Create a new directory Thot/Target
3. Create a new Thot/Target/Makefile by copying Thot/makes/Makefile.template and changing the values for THOTDIR, MACHINE, LINK_OPTIONS, CFLAGS, SYSTEM_FLAGS, MOTIFLIBS, STDLIBS and CC according to the source path, the Target value and the compilation environment.
4. Compile the graphic libraries by typing in the following commands:

   make libjpeg

   make libpng

   Hopefully, this will create libjpeg.a, libpng.a and libz.a in the Thot/Target directory.

   In case of problems, the sources are located in the Thot/libpng and Thot/libjpeg directories.

   You will probably notice errors and warning, you can safely ignore them as long as the libraries needed are generated.

5. Next step is to build the WWW library. The library building process is based on configure, which should simplify a lot the porting work needed, and the following command should produce the library libwww.a on most of the non-supported platforms:

   make libwww

6. The configure process for libwww produces a config.h file describing most of the specificities of the programming interface of the Target. Amaya and the Thot library use this file. It must be copied in the Thot/Target directory:

   cp ../w3c-libwww-5.0a/config.h .

7. Double check the content of the Makefile for the Target, especially values for CC, COMPIL_FLAGS, LINK_FLAGS. Verify all dependencies related to X-Window and Motif installation path.

From that point, compiling Amaya should be identical to compiling on a supported platfom. In case of problems, first check the following files:

1. Thot/thotlib/include/thot_sys.h : try to isolate dependencies with respect to the operating system programming interface.
2. Thot/thotlib/include/thot_gui.h : try to isolate dependencies with respect to the user interface programming interface.
3. Thot/Target/config.h : results obtained by autoconf on the Target system.

Of course the general rules for fighting compilation problems and problems running Amaya binary should be of interest.

If the porting process is stopped and there is no obvious solutions on how to solve the problem, send the error to the www-amaya@w3.org mailing-list. We can't guarantee that the Amaya team will be able to help out, but other people on the list may suggest new solutions on how to solve your problem.

If you succeed to port to a new platform, it would be of general interest to send to the mailing-list the modifications needed (use patch -p), as well as the config.h and the Makefile for the corresponding Target. We cannot guarantee that the patches will be incorporated in the general sources, but keeping them around may simplify the task for other users. If the changes are big, do not send them to the list, but store them in the ftp://opera.inrialpes.fr/incoming/ FTP site, and send a mail concerning their availability, thanks.