Compiling Amaya Sources with Autoconf

This document explains how to compile the Amaya environment (Amaya binary and Amaya schemas compilers) from the distributed source tree.

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

Prerequisite:

• We strongly recommend 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 latest versions (0.8.0 and later) of Lesstif (a free Motif clone).

How to build in 4 steps:

Here is a simple recipe explaining how to build using autoconf:

1. Install your source code tree:

   gunzip -c /tmp/amaya-src-xxx.tar.gz | tar xvf -

   this will create a Amaya subtree of approximately 13 MBytes.

2. Create a subtree (obj) for object and launch configure to create the Makefile(s):

   cd Amaya
   mkdir obj 
   cd obj 
   ../configure

   Configure accepts 4 specific parameters allowing to select packages to be compiled:

         
         --with-amaya            Build the Amaya HTML browser/editor
         --enable-java           Add Kaffe Java virtual machine
         --enable-plugin         Add Netscape Plug-Ins support

   Java (network accesses are done using libWWW) and Plugins are not available by default. To compile Amaya with Plugins, use the following:

    ../configure --enable-plugin
    

   To compile Amaya with Java support, you need to retrieve the Amaya-java source distribution. Then, you need to type the following:

    ../configure --enable-java
    

   This creates all the Makefiles needed and generate an Options.orig file containing all the variable which can be tuned. For example one can just change the CFLAGS values. Be careful, autoconf usually set up the debug flag "-g" which tends to generate very big library and binaries.

   With -g the obj tree can grow up to 100 MBytes while without it it won't use more than 20 MBytes.

   It also gives some hints on how the source tree is configured.

3. Build everything:

   make all

   It is strongly recommended to use GNU make, which may not be the default make on your system. In this case try:

   gmake all

   or

   gnumake all

   The compilation process can take a fair amount of time, 10 minutes at least.

   You can test the result immediately by launching Amaya binary built in the bin directory:

   bin/amaya

4. If amaya binary seems fine you can install it:

   make install

   By default, links to binaries are installed in /usr/local/bin, binaries and data are in /usr/local/thot. This can be overrided by specifying different values for prefix(es) using configure command line options in step 2.

   Ultimately, if you're not satisfied with your current Amaya installation, you can clean up with:

   make uninstall

More info on the make files

All the Makefile(s) build in the object tree are generated by configure script and Makefile.in templates found in the source tree. It generates a main Makefile at the top of the object tree and a set of Makefiles in most of the directory of the object tree. The main Makefile accepts the following targets:

• make rebuild : rebuild all the Makefile(s) from the autoconf and Makefile.in files.
• make depend : rebuild all the dependencies in the object tree.
• make proto : rebuild all the prototype include files xxx_f.h from their xxx.c counterpart.
• make clean : removes all object files, but keep the binaries in Amaya/obj /bin .
• make libwww : rebuild the libwww.a library from Amaya/libww tree.
• make libjpeg : rebuild the libjpeg.a library from Amaya/libjpeg tree.
• make libpng : rebuild the libpng.a and libz.a libraries from Amaya/libpng tree.
• make without argument rebuild everything.
• make amaya rebuild Print and Amaya binaries.

One can also go to a specific sub-directory in the object tree and launch make from that place. It will rebuild all the objects pertaining to this directory.

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

If make failed:

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

• from the start: typing make in the Amaya/obj directory doesn't work. This means that the step 1 or 2 of the previous section failed.
  1. do you use GNU make? The Makefile organization heavily relies on including sub-Makefiles and some old versions of Make don't support it.
  2. do you have write access on the Amaya/obj directory ?
  3. do you have all mandatory sources ?
• an error when compiling a C file occurred. 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 for the X-Windows and Motif include files in Amaya/obj /Options.
  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.
• an error running a compiler schema occurred:
  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 conjunction 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 Amaya/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 occurred at link time:
  1. Check that the current directory contains all the precompiled libraries, namely libjpeg.a, libpng.a and libz.a for the obj . 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 re-extract 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 Amaya/obj /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 Amaya/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 schemas are present, namely Amaya/amaya/HTML.STR, Amaya/amaya/HTMLP.PRS...
3. Verify that the main registry file Amaya/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.