Compiling Amaya Sources (old version)

The best way now to compile Amaya from sources is to use autoconf. Here are the information concerning the old build process which may be useful if autoconf make failed or if one already use the old building process.

This document explains how to compile the Amaya environment (Amaya binary and Thot schemas compilers) from the distributed source tree and on one of the platforms . In the following we will use Target for the platform nickname (e.g. solaris2 for a Sun workstation running Solaris 2.5). Adding support to for a new achitecture is explained in the porting section.

Here is the content of this document:

1. prerequisite
2. How to build
3. More info on the make files
4. More info on the build process
5. If make failed
6. If amaya binary doesn't work
7. If everything suceeded

Prerequisite:

The complete source tree must have been set-up accordingly to the source distribution installation instructions.

• We suggest to use a GNU make and if possible GNU CC since these are the tools used by the Amaya Team, and very few testings have been done with other flavours of make and C compilers.
• Having usual Unix development tools, at least sed, awk and cpp should be available.
• Amaya requires X-Windows (X11R5 or X11R6) and Motif (1.2.x or 2.0). Amaya should now work fine with latests versions (0.8.0 and later) of Lesstif (a free Motif clone).

How to build, short version:

Here is a simple recipe explaining how to build on one of the supported target:

• cd to Thot/Target directory.
• copy the Makefile.orig file to Makefile. Edit the first top lines to change THOTDIR to the base of the current Amaya tree e.g:

  THOTDIR=$(HOME)/Thot

• Also check in Makefile that you have the AMAYA_OPTIONS selected for libWWW:

  AMAYA_OPTIONS = -DCOUGAR

  AMAYA_LIBS =

  AMAYA_LINK = -lwww

  And that the options selecting Java are commented out.

• Ensure that the current directory contains all the precompiled libraries, namely libwww.a, libjpeg.a, libpng.a and libz.a as well as the config.h file describing the Target. If these files are lacking, fetch the appropriate thot-libs-Target-xxx.tar.g distribution file and install it.
• type in the following command:

  make

  make amaya

  Time for a comfortable coffee break (take 12 mn. on a 200 MHz Pentium-Pro).

  This will create a subtree of Thot/Target, similar in it's shape with the source one and populate it with the object resulting of the make. The binaries and libraries produced are stored in the Thot/Target/bin directory.

If everything went well, the following files should be available in the Thot/Target/bin directory:

• amaya : the Amaya binary
• print : the amaya printing subprocess binary.
• app, grm, prs, str, tra, typ, printstr, printpr, rescandialogue : various compilers and utilities.
• libThotEditor.a : the main Thot library.
• libThotKernel.a : the core Thot library.

One can test the resulting Amaya binary by starting bin/amaya from the shell.

More on the make files:

The Thot/makes directory contains a few important files related to Amaya compilation process:

• Make.files : contains a list of directories, C files, header files, it is automatically generated and should not be edited.
• Make.depends : contains all the dependencies between C files and header files. Again, this is automatically generated and should not be edited.
• CommonMake : this contains all the make rules needed to build the Amaya application, compilers, etc. This file is included from all Thot/Target/Makefile and is also automatically generated. CommonMake includes Make.depends.
• Imakefile, Imake.rules, Imake.tmpl and makemake: these are used to rebuild CommonMake from the Imakefile (containing all the modules definitions) and a few specific imake rules. The makemake script call imake to build CommonMake from the Imake files.
• Makefile : generic makefile used to set up the compilation environment. It handle the following make targets:
  • make rebuild : rebuild Make.files by browsing the Amaya tree.
  • make depend : rebuild Make.depends, extracting the list of C files from Make.files. If needed it will rebuild Thot/Target/bin/mkdep used to generate the dependencies.
  • make proto : rebuild the various function prototype header files xxx_f.h located in the Thot/thotlib/internals/f , Thot/batch/f and Thot/amaya/f directories. We use a modified version of cextract-1.7 to generate these headers from the function definition found in the C files. If not present the Thot/Target/bin/cextract binary is built on the fly.

As explained above, the Makefile found in the Thot/Target directory consists of a few options related to the corresponding platform and include Thot/makes/CommonMake containing all the make rules. Here is a description of all the main make targets found in the CommonMake and hence available when typing make from Thot/Target directory:

• make rebuild : see above.
• make depend : see above.
• make proto : see above.
• make clean : removes all object files, but keep the binaries and libraries in Thot/Target/bin .
• make libwww : rebuild the libwww.a library from Thot/w3c-libwww-5.0a tree.
• make libjpeg : rebuild the libjpeg.a library from Thot/libjpeg tree.
• make libpng : rebuild the libpng.a and libz.a libraries from Thot/libpng tree.
• make without argument rebuild the compilers and print.
• make amaya rebuild Amaya binary.

More info on the build process

Here are the steps done when starting make in the Thot/Target directory:

1. make fetch the current Makefile, ../makes/CommonMake, ../makes/Make.files and ../makes/Make.depends, if the latests are non-existent it tries to rebuild them and stop.
2. if needed make build all the directories needed to receive the objects files and the results from the compilation, for example Thot/Target/bin , Thot/Target/thotlib/base, etc.
3. make build Thot/Target/bin/libThotKernel.a from subset of the Thot/thotdir sources. This involve compiling the C files, creating the archive with ar and running ranlib against the archive.
4. make create the compilers associated to the Thot library using the libThotKernel.a
   1. grm
   2. str
   3. prs
   4. tra
   5. app
   6. rescandialogue
5. make build Thot/Target/bin/libThotEditor.a from the Thot/thotdir sources. This involve compiling the C files, creating the archive with ar and running ranlib against the archive.
6. make build print using

Next steps are related to the make amaya execution:

7. the make process start str compiler on the Thot/amaya/HTML.S describing the structure schema of an HTML document. This produce the Thot/amaya/HTML.STR file.
8. then the prs compiler is called to compile the four presentation schema for displaying HTML document in color displays, for printing, for printing on US Letter paper format and for black-and-white displays. This produces .PRS files from the HTMLP.P presentation schema.
9. the tra compiler is used to compile Thot/amaya/HTMLT.T to HTMLT.TRA . This direct the generation of an HTML file from the Thot internal represenation of the document.
10. the app compiler compiles the HTML.A describing the HTML specific user interface of Amaya into the HTML.h header, the HTMLAPP.c code and a prototype file HTMLactions.proto for the interface callbacks (the actual file used is HTMLactions.c).
11. the app compiler compiles the EDITOR.A describing the generic user interface of Amaya into the EDITOR.h header, the EDITORAPP.c code, the EDITORdialogue ressource file and a prototype file EDITORactions.proto for the interface callbacks (the actual file used is EDITORactions.c).
12. then make compiles the C files from the Thot/amaya directory to objects.
13. Lastly make links amaya object files, with the libThotEditor.a , the graphic libraries, the WWW library, Motif, Intrinsics, X-Windows and math to produce the Amaya binary.

Next section try to give some hint on debugging errors at compile-time.

If make failed:

Errors may append at diffferent stages in the compilation process. Here is a small checklist:

• from the start: typing make in the Thot/Target directory doesn't work. This means that the step 1 or 2 of the previous section failed.
  1. did you edit Makefile to reflect the proper THOTDIR value ?
  2. do you use GNU make? The Makefile organization heavily relies on including sub-Makefiles and some old versions of Make don't support it.
  3. dou you have write access on the Thot/Target directory ?
  4. is the Thot/Target/config.h file present ? If not, fetch the the appropriate thot-libs-target-xxx.tar.gz distribution file and install it.
  5. are ../makes/Make.files and ../makes/Makes.depends files present ? If not, make will try to build them but with some versions of make this is not

     possible. In this case, cd to ../makes and type

     make rebuild ; make depend

     to rebuild both files. Go back in the Thot/Target directory and restart make.

• an error when compiling a C file occured. This should not be the case on any of the supported platform:
  1. check that you have some room left for the object.
  2. verify the include path (-I flags in COMPILOPTIONS) for the X-Windows and Motif include files in Thot/Target/Makefile.
  3. verify that the target directory for the object exist and is writable. The object name is shown in the make output behind the -o flag.
  4. check that you are using an ANSI compliant compiler, while the code should compile with non-ANSI ones, we don't test this feature on a regular basis.
  5. If the error occurs when compiling a C file in the amaya directory, check that all the compilers invocations in steps 7 to 11 did not produce any error (the Thot compilers are verbose so errors messages may not be easily detected).
  6. otherwise your best bet is to report the problem to the Amaya development Team, by sending the error to the www-amaya@w3.org mailing-list. Please check first the archive, the error may have been already reported.

  On an unsupported platform see the document on porting to an new platform

• an error running a compiler schema occured:
  1. be sure that the compilers were properly build in step 5, check with ldd that there is no missing shared library, e.g:

     ldd bin/app

  2. be sure that cpp preprocessor is in the PATH. One can use the following shell script in conjuction with gcc, name it cpp, put it in the PATH with 755 Unix rights:

     #!/bin/sh
             exec `gcc --print-prog-name=cpp` $*

  3. check that you have write right access on Thot/amaya directory.
  4. One can force the compiler to rebuild the amaya and HTML schemas by typing:

     touch ../amaya/*.S

     touch ../amaya/*.A

     make amaya

• an error occured at link time:
  1. Check that the current directory contains all the precompiled libraries, namely libjpeg.a, libpng.a and libz.a for the Target. If these files are lacking, fetch the appropriate thot-libs-target-xxx.tar.gz distribution file and install it.
  2. Check that the precompiled libraries are not corrupted e.g.:

     file libwww.a

     nm libwww.a

     should not print any errors

  3. In case of a corrupted library, one can reextract it from the distribution file or rebuild it by giving one of the appropriate commands:

     make libjpeg

     make libpng

     make libwww

     In case of problem building the WWW library, please check it's installation instructions. Compiling the graphic libraries should be quite straightforward.

  4. verify the library path (-L flags in LINK_OPTIONS) for the X-Windows and Motif libraries files in Thot/Target/Makefile.
  5. Check whether -lSM and -lICE X11R6 libraries are needed. These were not needed (available) when working on an X11R5 environment.
  6. If amaya linking complains about XLookupString, check in Thot/amaya/EDITOR.A that the section USES does not refer to Lookup. If needed, remove it, and restart

     make amaya

     This is related to the input of ISO-Latin-1 sequences in Motif dialog boxes.

  7. Otherwise your best bet is to report the problem to the Amaya development Team, by sending the error to the www-amaya@w3.org mailing-list. Please check first the archive, the error may have been already reported

If amaya binary doesn't work:

Here is a few rules to check if the amaya binary just produced does not start:

1. Check that the shared libraries needed by amaya are found on the system. The command

   ldd bin/amaya on Suns or Linux

   chatr bin/amaya on HP's

   should print all the shared libraries needed by amaya and the path to the corresponding libraries in the system.

2. Check that the amaya compiled shemas are present, namely Thot/amaya/HTML.STR, Thot/amaya/HTMLP.PRS.
3. Verify that the main registry file Thot/config/thot.ini is present.

If everything seems Ok, one can debug the problem by using a system call tracer like truss on Solaris or strace on Linux. Check for syscalls errors near the end of the system trace dump.

All the remaining technics to find out what's wrong are software debugging methods, for this of course one need to recompile the binary with debug option enabled, and use a debugger program to see what's happening exactly. Once a bug has been identified, please report it to the Amaya development Team, by sending the error to the www-amaya@w3.org mailing-list. Please check first the archive, the error may have been already reported. Of course, sending a contextual diff of the modified files may help correcting the problem, and have it patched on next release.

If everything succeeded

You might want to try to build the Amaya with Java version. In these case follow the specific instructions for compiling Amaya with Java.